xaaha/hulak가벼운 파일 기반 CLI API 클라이언트로, age로 암호화된 시크릿, 일급 GraphQL 지원, AI 에이전트 워크플로를 위한 내장 MCP 서버를 갖추고 있습니다.
<p align="center">
<img alt="Hulak" src="https://raw.githubusercontent.com/xaaha/hulak/main/assets/hulak-logo.svg" width="180" />
</p>
<h1 align="center">Hulak</h1>
<h3 align="center">
터미널 속 당신의 메신저.
</h3>
<p align="center">
<a href="#quick-start">빠른 시작</a> •
<a href="#graphql-explorer">GraphQL 탐색기</a> •
<a href="#project-layout">프로젝트 구조</a> •
<a href="#documentation">문서</a>
</p>
---
### 단일 요청, 디렉터리 전체 실행, 또는 대화형 모드 유지
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
Hulak은 프로젝트에서 직접 요청 파일을 실행합니다. 동시 디렉터리 실행을 지원합니다. `hulak`만 실행하면 대화형 선택기로 전환됩니다.
### 전용 GraphQL 탐색기
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
여러 엔드포인트의 스키마를 탐색합니다. 작업을 검색합니다. 대화형으로 쿼리를 작성합니다. 인라인으로 실행합니다. 터미널에서 생성된 파일을 저장합니다.
## 빠른 시작
### 설치
Hulak은 [xaaha/tap](https://github.com/xaaha/homebrew-tap)을 통해 배포됩니다. Homebrew 6.0+는 서드파티 tap에 대한 명시적 신뢰를 요구합니다. 신뢰하지 않으면 `brew upgrade`가 hulak을 조용히 건너뜁니다. 머신당 한 번만 수행하면 됩니다:
```bash
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`로 설치했거나
소스에서 빌드한 경우, 한 번만 설정하세요:
```bash
# 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 클라이언트 (기본)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
시작용 요청을 스캐폴딩하려면, 요청 파일이 어떻게 생겼는지 빠르게 확인하려면 다음을 실행하세요:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> 다른 유형은 다음을 실행하세요: `hulak example`. `example` 하위 명령은 수정할 수 있는 요청 파일을 빠르게 작성하는 방법을 제공합니다. 더 많은 정보는 `hulak example -h`를 실행하세요.
시크릿을 설정하려면 다음을 실행할 수 있습니다:
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
이제 `example-api.hk.yaml` 파일에서 이 시크릿을 참조할 수 있습니다:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
요청을 실행하세요:
```bash
hulak run example-api.hk.yaml --env prod
```
### 암호화된 시크릿 대신 평문 `env/*.env` 파일을 선호하시나요?
```bash
hulak init classic
```
평문 모드는 완전히 지원됩니다. 자세한 내용은 [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md)를 참조하세요
## 암호화된 시크릿 볼트 또는 평문 `.env` 파일
Hulak은 두 가지 모드로 실행됩니다. `hulak init` 중에 한 번 선택하세요. 나중에 마이그레이션할 수 있습니다.
- **볼트 (기본):** 시크릿은 `.hulak/store.age`에 저장되며, age 또는 SSH 키페어로 암호화됩니다. 커밋해도 안전합니다. 팀은 수신자 파일을 통해 공유합니다. [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md)를 참조하세요.
- **평문:** 시크릿은 평문 `env/*.env` 파일에 저장됩니다. 더 간단하고 암호화가 없습니다. `env/`를 `.gitignore`에 추가하세요. [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md)를 참조하세요.
클래식 모드를 실행 중이고 전환하고 싶으신가요? [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md)를 참조하세요.
## AI 에이전트에서 사용하기 (MCP)
Hulak은 내장 [MCP](https://modelcontextprotocol.io) 서버를 제공하므로 Claude Code, Cursor, Zed 같은 에이전트가 자연어로 API 컬렉션을 다룰 수 있습니다 — "요청 목록을 보여줘", "스테이징에 대해 `login`을 드라이런해줘", "`getUser`를 호출하고 응답을 보여줘".
Claude Code의 경우, 한 명령으로 추가하세요:
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
Cursor, Zed, Codex, opencode, Pi는 대신 작은 설정 파일을 사용합니다. 각각에 대해서는 [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md)를 참조하세요.
시크릿은 절대 당신의 머신을 떠나지 않습니다: 에이전트는 요청 및 환경 **이름**으로만 작업하며, 복호화된 값은 절대 다루지 않습니다. 읽기와 드라이런은 읽기 전용이고, 쓰기는 스키마 검증을 거치며, 요청하지 않는 한 응답 파일은 저장되지 않습니다.
전체 설정, 도구 레퍼런스, 안전 모델: [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## 명령어
| Command | Purpose | Read more |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | 요청 파일 또는 디렉터리 실행 | [body.md](https://github.com/xaaha/hulak/blob/main/docs/body.md), [actions.md](https://github.com/xaaha/hulak/blob/main/docs/actions.md) |
| `gql` | GraphQL 탐색기 TUI | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | 암호화된 볼트 CRUD | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | hulak 프로젝트 초기화 | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Postman에서 hulak으로 변환 | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | 샘플 요청 파일 스캐폴딩 | — |
| `doctor` | 프로젝트 상태 확인 | — |
| `mcp` | MCP를 통해 AI 에이전트에 요청 제공 | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/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](https://github.com/xaaha/hulak/blob/main/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](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts)를 참조하세요.
## 프로젝트 구조
```text
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 탐색기
파일 또는 디렉터리로 탐색기를 시작하세요:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
전체 가이드는 [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)에서 확인하세요.
## 문서
전체 레퍼런스는 여기서 시작하세요:
- [암호화된 저장소](https://github.com/xaaha/hulak/blob/main/docs/store.md). 암호화 모델, 팀 공유, CI.
- [볼트로 마이그레이션](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). `env/`에서 `.hulak/`로.
- [볼트 버전 관리](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). 시크릿을 위한 Git 워크플로.
- [비교](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak vs SOPS, Bruno 등.
- [요청 본문](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [액션](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [환경 시크릿 (클래식 모드)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [응답 파일](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [GraphQL 탐색기](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)
- [Auth 2.0](https://github.com/xaaha/hulak/blob/main/docs/auth20.md)
- [MCP 서버](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). AI 에이전트에 요청을 노출합니다.
실시간 명령 표면은 다음을 실행하세요:
```bash
hulak help
hulak <command> --help
```
## 스키마 지원
Hulak 스키마는 [Schema Store](https://www.schemastore.org/)에서 사용할 수 있으므로, Schema Store를 지원하는 편집기는 `.hk.yaml` 및 `.hk.yml` 파일에 대한 자동 완성을 자동으로 활성화할 수 있습니다.
YAML 언어 서버를 직접 다음으로 지정할 수도 있습니다:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## 기여
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
전체 개발 워크플로는 [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md)를 참조하세요.
## 프로젝트 지원
Hulak이 유용하다면, 이슈를 열거나, 기능을 제안하거나, 풀 리퀘스트를 보내거나, 프로젝트를 후원해 주세요.