Hulak

ターミナルの中のあなたのメッセンジャー。

クイックスタート • GraphQL エクスプローラー • プロジェクト構成 • ドキュメント

---

1 つのリクエスト、ディレクトリ全体、または対話モードで実行

hulak run ./requests/

Hulak はプロジェクトから直接リクエストファイルを実行します。ディレクトリの並行実行をサポートしています。単に hulak を実行すると、対話形式のピッカーにフォールバックします。

専用の GraphQL エクスプローラー

複数のエンドポイントからスキーマを閲覧できます。オペレーションを検索できます。クエリを対話的に構築できます。インラインで実行できます。生成されたファイルをターミナルから保存できます。

クイックスタート

インストール

Hulak は xaaha/tap 経由で配布されています。Homebrew 6.0 以降ではサードパーティの tap に対して明示的な信頼が必要です。これがないと、brew upgrade は hulak を黙ってスキップします。マシンごとに 1 回だけ実行してください:

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 を参照してください。

暗号化シークレット Vault または平文 .env ファイル

Hulak は 2 つのモードで動作します。hulak init の際に一度選択してください。後から移行できます。

• Vault (デフォルト): シークレットは .hulak/store.age に保存され、age または SSH キーペアで暗号化されます。コミットしても安全です。チームは recipients ファイル経由で共有します。詳細は docs/store.md を参照してください。
• 平文: シークレットは平文の env/*.env ファイルに保存されます。よりシンプルで、暗号化はありません。env/ を .gitignore に追加してください。詳細は docs/environment.md を参照してください。

classic モードで実行していて切り替えたい場合は、docs/migrating-to-vault.md を参照してください。

AI エージェントから使う (MCP)

Hulak には組み込みの MCP サーバーが同梱されているため、Claude Code、Cursor、Zed などのエージェントが自然言語で API コレクションを操作できます — 「リクエストを一覧表示して」「staging に対して login をドライランして」「getUser を呼び出してレスポンスを表示して」。

Claude Code の場合は、1 つのコマンドで追加できます:

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	暗号化 Vault の 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 は 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 を参照してください。

プロジェクト構成

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 を参照してください。

ドキュメント

完全なリファレンスはここから始めてください: