hulak v0.3.33
一个轻量级、基于文件的 CLI API 客户端，支持 age 加密密钥、一流的 GraphQL 支持，以及为 AI 代理工作流内置的 MCP 服务器。
Hulak
你的终端信使。
快速开始 • GraphQL 浏览器 • 项目结构 • 文档
运行单个请求、整个目录，或保持交互模式
hulak run ./requests/
Hulak 直接从你的项目中运行请求文件。它支持并发目录执行。当你只运行 hulak 时，它会回退到交互式选择器。
专用 GraphQL 浏览器
浏览来自多个端点的 schema。搜索操作。交互式构建查询。内联执行。从终端保存生成的文件。
快速开始
安装
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 # 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 有两种运行模式。在 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 了解各自的配置。
密钥永远不会离开你的机器：代理只使用请求和环境的名称，从不使用解密后的值。读取和试运行是只读的；写入会经过 schema 验证；除非被要求，否则不会保存响应文件。
完整设置、工具参考和安全模型：docs/mcp.md。
命令
| 命令 | 用途 | 了解更多 |
|---|---|---|
run | 执行请求文件或目录 | body.md, actions.md |
gql | GraphQL 浏览器 TUI | graphql-explorer.md |
secrets | 加密保险库 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除外）。- 非交互式 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 # 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。
文档
从这里开始获取完整参考：
- 加密存储。加密模型、团队共享、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。