hulak

原生 Git 的 API 客户端，内置加密密钥。

_{REST · GraphQL · OAuth}

快速开始 • 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 从源码构建

Shell 补全（go install / 源码构建）

Homebrew 会自动安装补全。如果你通过 go install 安装或从源码构建，请选择一次启用：

# zsh
hulak completion zsh > "${fpath[1]}/_hulak"        # 然后重启 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 # 创建 .hulak/store.age + identity

生成一个入门请求，快速查看请求文件的样子，请运行：

hulak example api  # 写入你可以运行的 example-api.hk.yaml

[!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 密钥对加密。可安全提交。团队通过 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，使用一条命令添加：

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 会打开一个交互式选择器。

• 仅当文件引用 {{.key}} 时，hulak run 和 hulak gql 才会提示。
• hulak secrets 子命令每次都提示（secrets list 除外）。
• 非交互式 shell 需要 --env <name>。

常见陷阱

• 切勿提交 ~/.config/hulak/identity.txt。 那是你的私钥。权限为 0600。先备份。参见 docs/store.md#identity-backup。
• hulak init 时，-env 用于创建环境文件。它是设置标志，不是运行时选择器。 hulak init -env staging prod 会生成两个环境。
• 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          # 加密密钥（可安全提交）
│   └── recipients.txt     # 接收者的公钥（可安全提交）
├── requests/
│   ├── create-user.hk.yaml
│   └── get-user.hk.yaml
└── (你的项目文件)

~/.config/hulak/
└── identity.txt           # 你的私钥。切勿提交。权限 0600。

GraphQL 资源浏览器

使用文件或目录启动资源浏览器：

hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql

完整指南请阅读 docs/graphql-explorer.md。

文档

从这里开始获取完整参考：

• 加密存储。加密模型、团队共享、CI。
• 迁移到保险库。从 env/ 迁移到 .hulak/。
• 为你的保险库做版本管理。密钥的 Git 工作流。
• 对比。Hulak 与 SOPS、Bruno 及其他工具的对比。
• 请求体
• 操作
• 环境密钥（classic 模式）
• 响应文件
• GraphQL 资源浏览器
• Auth 2.0
• MCP 服务器。将你的请求暴露给 AI 代理。

查看实时命令界面，请运行：

hulak help
hulak <command> --help

Schema 支持

Hulak schema 可在 Schema Store 中找到，因此支持 Schema Store 的编辑器可以自动为 .hk.yaml 和 .hk.yml 文件启用补全。

你也可以将 YAML 语言服务器直接指向：

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、建议功能、发送 pull request，或赞助该项目。