Hulak

터미널 속 당신의 메신저.

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

---

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

hulak run ./requests/

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

전용 GraphQL 탐색기

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

빠른 시작

설치

Hulak은 xaaha/tap을 통해 배포됩니다. Homebrew 6.0+는 서드파티 tap에 대한 명시적 신뢰를 요구합니다. 신뢰하지 않으면 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 키페어로 암호화됩니다. 커밋해도 안전합니다. 팀은 수신자 파일을 통해 공유합니다. 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.

명령어

Command	Purpose	Read more
run	요청 파일 또는 디렉터리 실행	body.md, actions.md
gql	GraphQL 탐색기 TUI	graphql-explorer.md
secrets	암호화된 볼트 CRUD	store.md
init	hulak 프로젝트 초기화	store.md
migrate	Postman에서 hulak으로 변환	migrating-to-vault.md
example	샘플 요청 파일 스캐폴딩	—
doctor	프로젝트 상태 확인	—
mcp	MCP를 통해 AI 에이전트에 요청 제공	mcp.md
version	버전 출력	—

플래그와 명령별 예제는 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에 대기 플래그가 필요합니다. EDITOR="code -w" 또는 EDITOR="zed --wait"를 사용하세요. 없으면 편집기가 즉시 반환되고 변경 사항이 손실됩니다.
• store.age의 병합 충돌에는 레시피가 필요합니다. docs/versioning.md#merge-conflicts를 참조하세요.

프로젝트 구조

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에서 확인하세요.

문서

전체 레퍼런스는 여기서 시작하세요: