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>
---
### 1 つのリクエスト、ディレクトリ全体、または対話モードで実行
<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 を黙ってスキップします。マシンごとに 1 回だけ実行してください:
```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) を参照してください。
## 暗号化シークレット Vault または平文 `.env` ファイル
Hulak は 2 つのモードで動作します。`hulak init` の際に一度選択してください。後から移行できます。
- **Vault (デフォルト):** シークレットは `.hulak/store.age` に保存され、age または SSH キーペアで暗号化されます。コミットしても安全です。チームは recipients ファイル経由で共有します。詳細は [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) を参照してください。
classic モードで実行していて切り替えたい場合は、[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 コレクションを操作できます — 「リクエストを一覧表示して」「staging に対して `login` をドライランして」「`getUser` を呼び出してレスポンスを表示して」。
Claude Code の場合は、1 つのコマンドで追加できます:
```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` | 暗号化 Vault の 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` は 2 つの 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) を参照してください。
## ドキュメント
完全なリファレンスはここから始めてください:
- [Encrypted Store](https://github.com/xaaha/hulak/blob/main/docs/store.md)。暗号化モデル、チーム共有、CI。
- [Migrating to the Vault](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md)。`env/` から `.hulak/` へ。
- [Versioning Your Vault](https://github.com/xaaha/hulak/blob/main/docs/versioning.md)。シークレットの Git ワークフロー。
- [Comparison](https://github.com/xaaha/hulak/blob/main/docs/comparison.md)。Hulak 対 SOPS、Bruno、その他。
- [Request Body](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Actions](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Environment Secrets (classic mode)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Response Files](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [GraphQL Explorer](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 Server](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 が役に立ったなら、issue を立てる、機能を提案する、プルリクエストを送る、またはプロジェクトをスポンサーしてください。