hulak

Git 네이티브 API 클라이언트, 암호화된 시크릿 지원.

_{REST · GraphQL · OAuth}

빠른 시작 • GraphQL 탐색기 • 프로젝트 구조 • 문서

단일 요청, 전체 디렉터리, 또는 대화형 모드로 실행

hulak run ./requests/

Hulak은 프로젝트에서 요청 파일을 직접 실행합니다. 디렉터리 동시 실행을 지원합니다. 단순히 hulak을 실행하면 대화형 선택기로 대체됩니다.

전용 GraphQL 탐색기

여러 엔드포인트의 스키마를 탐색합니다. 작업을 검색합니다. 쿼리를 대화형으로 작성합니다. 인라인으로 실행합니다. 터미널에서 생성된 파일을 저장합니다.

빠른 시작

설치

Hulak은 xaaha/tap을 통해 배포됩니다. Homebrew 6.0+는 서드파티 탭에 대한 명시적 신뢰 설정이 필요합니다. 이를 설정하지 않으면 brew upgrade가 hulak을 조용히 건너뜁니다. 기기당 한 번만 수행하면 되는 단계:

brew trust xaaha/tap
brew install --cask xaaha/tap/hulak

기타 설치 옵션:

• go install github.com/xaaha/hulak@latest
• 소스에서 빌드: go build -o hulak

셸 자동완성 (go install / 소스 빌드)

Homebrew는 자동완성을 자동으로 설치합니다. go install로 설치했거나 소스에서 빌드했다면 한 번만 활성화하세요:

# zsh
hulak completion zsh > "${fpath[1]}/_hulak"        # then restart your shell

# bash (macOS, Homebrew bash-completion)
hulak completion bash > $(brew --prefix)/etc/bash_completion.d/hulak

# bash (Linux)
hulak completion bash | sudo tee /etc/bash_completion.d/hulak >/dev/null

Zsh는 .zshrc에 autoload -Uz compinit && compinit이 필요합니다.

경로 A. 암호화된 시크릿을 사용하는 API 클라이언트 (기본값)

mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity

시작용 요청을 스캐폴드합니다. 요청 파일의 형태를 빠르게 확인하려면 다음을 실행하세요:

hulak example api  # writes example-api.hk.yaml you can run

[!Note] 다른 유형은 hulak example을 실행하세요. example 하위 명령은 수정할 수 있는 요청 파일을 빠르게 작성할 수 있는 방법을 제공합니다. 자세한 내용은 hulak example -h를 실행하세요.

시크릿을 설정하려면 다음을 실행할 수 있습니다:

hulak secrets keys set placeholder  https://jsonplaceholder.typicode.com/posts -env prod

이제 example-api.hk.yaml 파일에서 이 시크릿을 참조할 수 있습니다:

method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same

요청 실행:

hulak run example-api.hk.yaml --env prod

암호화된 시크릿 대신 일반 텍스트 env/*.env 파일을 선호하시나요?

hulak init classic

일반 텍스트 모드는 완전히 지원됩니다. 자세한 내용은 docs/environment.md를 참조하세요.

암호화된 시크릿 볼트 또는 일반 텍스트 .env 파일

Hulak은 두 가지 모드로 실행됩니다. hulak init 중에 한 번 선택하세요. 나중에 마이그레이션할 수 있습니다.

• 볼트(기본값): 시크릿은 .hulak/store.age에 저장되며 age 또는 SSH 키페어로 암호화됩니다. 커밋해도 안전합니다. 팀은 recipients 파일을 통해 공유합니다. docs/store.md를 참조하세요.
• 일반 텍스트: 시크릿은 일반 텍스트 env/*.env 파일에 저장됩니다. 더 간단하며 암호화가 없습니다. env/를 .gitignore에 추가하세요. docs/environment.md를 참조하세요.

클래식 모드를 사용 중이고 전환하고 싶으신가요? docs/migrating-to-vault.md를 참조하세요.

AI 에이전트에서 사용하기 (MCP)

Hulak에는 내장 MCP 서버가 포함되어 있어 Claude Code, Cursor, Zed와 같은 에이전트가 일반 언어로 API 컬렉션을 구동할 수 있습니다 — "요청 목록 나열", "스테이징 환경에서 login 드라이런", "getUser 호출 후 응답 표시" 등.

Claude Code의 경우 한 줄의 명령으로 추가하세요:

claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests

Cursor, Zed, Codex, opencode, Pi는 대신 작은 구성 파일을 사용합니다. 각각에 대한 내용은 docs/mcp.md를 참조하세요.

시크릿은 절대 머신을 벗어나지 않습니다. 에이전트는 요청 및 환경 이름으로만 작업하며 복호화된 값을 다루지 않습니다. 읽기와 드라이런은 읽기 전용입니다. 쓰기는 스키마 검증을 거치며, 요청하지 않으면 응답 파일이 저장되지 않습니다.

전체 설정, 도구 참조, 안전 모델: docs/mcp.md.

명령

플래그와 명령별 예제를 보려면 hulak <command> --help를 실행하세요.

선택기 동작

--env를 생략하면 대화형 선택기가 열립니다.

• hulak run 및 hulak gql은 파일이 {{.key}}를 참조할 때만 프롬프트를 표시합니다.
• hulak secrets 하위 명령은 매번 프롬프트를 표시합니다 (secrets list 제외).
• 비대화형 셸에서는 --env <name>이 필요합니다.

자주 발생하는 문제

• ~/.config/hulak/identity.txt를 절대 커밋하지 마세요. 이것은 당신의 개인 키입니다. 모드 0600. 먼저 백업하세요. docs/store.md#identity-backup을 참조하세요.
• hulak init에서 -env는 env 파일을 생성합니다. 설정 플래그이지 런타임 선택기가 아닙니다. hulak init -env staging prod는 두 개의 env를 스캐폴드합니다.
• env는 secrets의 별칭입니다. hulak env list는 hulak secrets list와 동일하게 동작합니다.
• GUI 편집기는 secrets edit에 wait 플래그가 필요합니다. EDITOR="code -w" 또는 EDITOR="zed --wait"를 사용하세요. 이 플래그가 없으면 편집기가 즉시 반환되어 변경 사항이 손실됩니다.
• store.age의 병합 충돌에는 해결 방법이 필요합니다. 를 참조하세요.

프로젝트 구조

my-project/
├── .hulak/
│   ├── store.age          # encrypted secrets (safe to commit)
│   └── recipients.txt     # public keys of recipients (safe to commit)
├── requests/
│   ├── create-user.hk.yaml
│   └── get-user.hk.yaml
└── (your project files)

~/.config/hulak/
└── identity.txt           # YOUR private key. NEVER commit. Mode 0600.

GraphQL 탐색기

파일 또는 디렉터리로 탐색기를 시작하세요:

hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql

전체 가이드는 docs/graphql-explorer.md에서 읽으세요.

문서

전체 참조 문서는 여기서 시작하세요:

• 암호화 스토어. 암호화 모델, 팀 공유, CI.
• 볼트로 마이그레이션. env/에서 .hulak/으로.
• 볼트 버전 관리. 시크릿을 위한 Git 워크플로.
• 비교. Hulak vs SOPS, Bruno 등.
• 요청 본문
• 액션
• 환경 시크릿 (클래식 모드)
• 응답 파일
• GraphQL 탐색기
• 인증 2.0
• MCP 서버. 요청을 AI 에이전트에 노출합니다.

실시간 명령 목록은 다음을 실행하세요:

hulak help
hulak <command> --help

스키마 지원

Hulak 스키마는 Schema Store에서 제공되므로 Schema Store를 지원하는 편집기는 .hk.yaml 및 .hk.yml 파일에 대해 자동 완성을 활성화할 수 있습니다.

또한 YAML 언어 서버를 다음 URL로 직접 지정할 수 있습니다:

https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json

기여

git clone https://github.com/xaaha/hulak.git
cd hulak
mise install

전체 개발 워크플로는 CONTRIBUTING.md를 참조하세요.

프로젝트 지원

Hulak이 유용하다면 이슈를 열거나, 기능을 제안하거나, 풀 리퀘스트를 보내거나, 프로젝트를 스폰서하세요.