<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>
---
### 运行单个请求、整个目录，或保持交互模式
<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" />
浏览来自多个端点的 schema。搜索操作。交互式构建查询。内联执行。从终端保存生成的文件。
## 快速开始
### 安装
Hulak 通过 [xaaha/tap](https://github.com/xaaha/homebrew-tap) 分发。Homebrew 6.0+ 要求对第三方 tap 显式信任；否则 `brew upgrade` 会静默跳过 hulak。每台机器只需执行一次：
```bash
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` 安装或从源码构建，需要手动启用一次：
```bash
# 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 客户端（默认）
```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)
## 加密密钥保险库或明文 `.env` 文件
Hulak 有两种运行模式。在 `hulak init` 时选择一次。之后可以迁移。
- **保险库（默认）：** 密钥存放在 `.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，用一条命令添加：
```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) 了解各自的配置。
密钥永远不会离开你的机器：代理只使用请求和环境的**名称**，从不使用解密后的值。读取和试运行是只读的；写入会经过 schema 验证；除非被要求，否则不会保存响应文件。
完整设置、工具参考和安全模型：[docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md)。
## 命令
| 命令 | 用途 | 了解更多 |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `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` | 加密保险库 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` 除外）。
- 非交互式 shell 需要 `--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` 创建环境文件。它是一个设置标志，不是运行时选择器。** `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](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)。
## 文档
从这里开始获取完整参考：
- [加密存储](https://github.com/xaaha/hulak/blob/main/docs/store.md)。加密模型、团队共享、CI。
- [迁移到保险库](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md)。从 `env/` 到 `.hulak/`。
- [为你的保险库进行版本控制](https://github.com/xaaha/hulak/blob/main/docs/versioning.md)。密钥的 Git 工作流。
- [对比](https://github.com/xaaha/hulak/blob/main/docs/comparison.md)。Hulak 与 SOPS、Bruno 等的对比。
- [请求体](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [操作](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [环境密钥（classic 模式）](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [响应文件](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [GraphQL 浏览器](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 服务器](https://github.com/xaaha/hulak/blob/main/docs/mcp.md)。将你的请求暴露给 AI 代理。
要查看实时命令界面，请运行：
```bash
hulak help
hulak <command> --help
```
## Schema 支持
Hulak schema 已在 [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、建议功能、发送 pull request，或赞助该项目。
