hulak

GitネイティブAPIクライアント（暗号化シークレット対応）。

_{REST · GraphQL · OAuth}

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

1つのリクエスト、ディレクトリ全体、またはインタラクティブモードで実行

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 は2つのモードで動作します。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 を staging に対してドライランして」「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

コマンド

フラグとコマンド別の例については 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 は環境ファイルを作成します。これはセットアップ用フラグであり、実行時のセレクタではありません。 hulak init -env staging prod は2つの環境を雛形生成します。
• env は secrets のエイリアスです。 hulak env list は hulak secrets list と同じように動作します。
• GUIエディタで secrets edit を使うには待機フラグが必要です。 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 を参照してください。

ドキュメント

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

• Encrypted Store。暗号化モデル、チーム共有、CI。
• Migrating to the Vault。env/ から .hulak/ への移行。
• Versioning Your Vault。シークレットのGitワークフロー。
• Comparison。Hulak vs SOPS、Bruno、その他。
• Request Body
• Actions
• Environment Secrets（クラシックモード）
• Response Files
• GraphQL Explorer
• Auth 2.0
• MCP Server。リクエストを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 が役に立つなら、issue を開いたり、機能を提案したり、プルリクエストを送ったり、プロジェクトをスポンサーしてください。