Skip to content
Back to search

hulak

Lightweight file-based CLI API client with age-encrypted secrets, first-class GraphQL support and MCP server for agentic workflow.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xaaha--hulak/badge.svg)](/listings/xaaha--hulak)

HTML

<a href="/listings/xaaha--hulak"><img src="/api/listings/xaaha--hulak/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

Hulak ships via [xaaha/tap](https://github.com/xaaha/homebrew-tap). Homebrew 6.0+ requires explicit trust for third-party taps; without it, `brew upgrade` silently skips hulak. One-time step per machine:

brew trust xaaha/tap
brew install --cask xaaha/tap/hulak

Other install options:

- `go install github.com/xaaha/hulak@latest` - Build from source with `go build -o hulak`

Shell completion (go install / source builds)

Homebrew installs completion automatically. If you installed via `go install` or built from source, opt in once:

# 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 requires `autoload -Uz compinit && compinit` in your `.zshrc`.

Path A. API client with encrypted secrets (default)

mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity

Scaffold a starter request, to quickly check how a request file looks run:

hulak example api  # writes example-api.hk.yaml you can run

> [!Note] > For Other types run: `hulak example`. `example` sub-command gives you a quick way to write a request file you can modify. For more info run `hulak example -h`

To set up a secret you can run:

hulak secrets keys set placeholder  https://jsonplaceholder.typicode.com/posts -env prod

Now, in your `example-api.hk.yaml` file, you can reference this secret:

method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same

Run the request:

hulak run example-api.hk.yaml --env prod

Prefer plaintext `env/*.env` files instead of encrypted secrets?

hulak init classic

Plaintext mode is fully supported. See [docs/environment.md](./docs/environment.md) for more info

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 245 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img alt="Hulak" src="./assets/hulak-logo.svg" width="180" />
  3. </p>
  4. <h1 align="center">Hulak</h1>
  5. <h3 align="center">
  6. Your messenger in the terminal.
  7. </h3>
  8. <p align="center">
  9. <a href="#quick-start">Quick Start</a> &bull;
  10. <a href="#graphql-explorer">GraphQL Explorer</a> &bull;
  11. <a href="#project-layout">Project Layout</a> &bull;
  12. <a href="#documentation">Documentation</a>
  13. </p>
  14. ---
  15. ### Run one request, a whole directory, or stay interactive
  16. <img alt="Concurrent Execution" src="./assets/concurrent.gif" width="720" />
  17. ```bash
  18. hulak run ./requests/
  19. ```
  20. Hulak runs request files directly from your project. It supports concurrent directory execution. It falls back to an interactive picker when you simply run `hulak`.
  21. ### Dedicated GraphQL Explorer
  22. <img alt="GraphQL Explorer" src="./assets/gql.gif" width="720" />
  23. Browse schemas from multiple endpoints. Search operations. Build queries interactively. Execute inline. Save generated files from the terminal.
  24. ## Quick Start
  25. ### Install
  26. Hulak ships via [xaaha/tap](https://github.com/xaaha/homebrew-tap). Homebrew 6.0+ requires explicit trust for third-party taps; without it, `brew upgrade` silently skips hulak. One-time step per machine:
  27. ```bash
  28. brew trust xaaha/tap
  29. brew install --cask xaaha/tap/hulak
  30. ```
  31. Other install options:
  32. - `go install github.com/xaaha/hulak@latest`
  33. - Build from source with `go build -o hulak`
  34. #### Shell completion (go install / source builds)
  35. Homebrew installs completion automatically. If you installed via `go install`
  36. or built from source, opt in once:
  37. ```bash
  38. # zsh
  39. hulak completion zsh > "${fpath[1]}/_hulak" # then restart your shell
  40. # bash (macOS, Homebrew bash-completion)
  41. hulak completion bash > $(brew --prefix)/etc/bash_completion.d/hulak
  42. # bash (Linux)
  43. hulak completion bash | sudo tee /etc/bash_completion.d/hulak >/dev/null
  44. ```
  45. Zsh requires `autoload -Uz compinit && compinit` in your `.zshrc`.
  46. ### Path A. API client with encrypted secrets (default)
  47. ```bash
  48. mkdir my-apis && cd my-apis
  49. hulak init # creates .hulak/store.age + identity
  50. ```
  51. Scaffold a starter request, to quickly check how a request file looks run:
  52. ```bash
  53. hulak example api # writes example-api.hk.yaml you can run
  54. ```
  55. > [!Note]
  56. > For Other types run: `hulak example`. `example` sub-command gives you a quick way to write a request file you can modify. For more info run `hulak example -h`
  57. To set up a secret you can run:
  58. ```bash
  59. hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
  60. ```
  61. Now, in your `example-api.hk.yaml` file, you can reference this secret:
  62. ```yaml
  63. method: POST
  64. url: "{{.placeholder}}"
  65. # rest of the body of the file remains same
  66. ```
  67. Run the request:
  68. ```bash
  69. hulak run example-api.hk.yaml --env prod
  70. ```
  71. ### Prefer plaintext `env/*.env` files instead of encrypted secrets?
  72. ```bash
  73. hulak init classic
  74. ```
  75. Plaintext mode is fully supported. See [docs/environment.md](./docs/environment.md) for more info
  76. ## Encrypted Secrets Vault Or Plaintext `.env` files
  77. Hulak runs in two modes. Pick once during `hulak init`. You can migrate later.
  78. - **Vault (default):** secrets live in `.hulak/store.age`, encrypted with an age or SSH keypair. Safe to commit. Teams share via a recipients file. See [docs/store.md](./docs/store.md).
  79. - **Plaintext:** secrets live in plaintext `env/*.env` files. Simpler, no encryption. Add `env/` to `.gitignore`. See [docs/environment.md](./docs/environment.md).
  80. Running classic and want to switch? See [docs/migrating-to-vault.md](./docs/migrating-to-vault.md).
  81. ## Use it from an AI agent (MCP)
  82. Hulak ships a built-in [MCP](https://modelcontextprotocol.io) server, so agents like Claude Code, Cursor, and Zed can drive your API collection in plain language — "list the requests", "dry-run `login` against staging", "call `getUser` and show the response".
  83. For Claude Code, add it with one command:
  84. ```bash
  85. claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
  86. ```
  87. Cursor, Zed, Codex, opencode, and Pi use a small config file instead. See [docs/mcp.md](./docs/mcp.md) for each.
  88. Secrets never leave your machine: the agent works with request and environment **names**, never decrypted values. Reads and dry-runs are read-only; writes are schema-validated; response files aren't saved unless asked.
  89. Full setup, tool reference, and safety model: [docs/mcp.md](./docs/mcp.md).
  90. ## Commands
  91. | Command | Purpose | Read more |
  92. | --------- | -------------------------------------- | ---------------------------------------------------------- |
  93. | `run` | Execute request file(s) or a directory | [body.md](./docs/body.md), [actions.md](./docs/actions.md) |
  94. | `gql` | GraphQL explorer TUI | [graphql-explorer.md](./docs/graphql-explorer.md) |
  95. | `secrets` | Encrypted vault CRUD | [store.md](./docs/store.md) |
  96. | `init` | Initialize a hulak project | [store.md](./docs/store.md) |
  97. | `migrate` | Postman to hulak conversion | [migrating-to-vault.md](./docs/migrating-to-vault.md) |
  98. | `example` | Scaffold sample request files | — |
  99. | `doctor` | Check project health | — |
  100. | `mcp` | Serve requests to AI agents over MCP | [mcp.md](./docs/mcp.md) |
  101. | `version` | Print version | — |
  102. Run `hulak <command> --help` for flags and per-command examples.
  103. ### Picker behavior
  104. Omitting `--env` opens an interactive picker.
  105. - `hulak run` and `hulak gql` only prompt when files reference `{{.key}}`.
  106. - `hulak secrets` subcommands prompt every time (except `secrets list`).
  107. - Non-interactive shells require `--env <name>`.
  108. ## Common Pitfalls
  109. - **Never commit `~/.config/hulak/identity.txt`.** That is your private key. Mode 0600. Back it up first. See [docs/store.md#identity-backup](./docs/store.md#identity-backup).
  110. - **On `hulak init`, `-env` creates env files. It is a setup flag, not a runtime selector.** `hulak init -env staging prod` scaffolds two envs.
  111. - **`env` is an alias for `secrets`.** `hulak env list` works the same as `hulak secrets list`.
  112. - **GUI editors need a wait flag for `secrets edit`.** Use `EDITOR="code -w"` or `EDITOR="zed --wait"`. Without it the editor returns immediately and changes are lost.
  113. - **Merge conflicts on `store.age` need a recipe.** See [docs/versioning.md#merge-conflicts](./docs/versioning.md#merge-conflicts).
  114. ## Project layout
  115. ```text
  116. my-project/
  117. ├── .hulak/
  118. │ ├── store.age # encrypted secrets (safe to commit)
  119. │ └── recipients.txt # public keys of recipients (safe to commit)
  120. ├── requests/
  121. │ ├── create-user.hk.yaml
  122. │ └── get-user.hk.yaml
  123. └── (your project files)
  124. ~/.config/hulak/
  125. └── identity.txt # YOUR private key. NEVER commit. Mode 0600.
  126. ```
  127. ## GraphQL Explorer
  128. Start the explorer with a file or a directory:
  129. ```bash
  130. hulak gql e2etests/gql_schemas/countries.yml
  131. hulak gql .
  132. hulak gql -env staging ./collections/graphql
  133. ```
  134. Read the full guide in [docs/graphql-explorer.md](./docs/graphql-explorer.md).
  135. ## Documentation
  136. Start here for the full reference:
  137. - [Encrypted Store](./docs/store.md). Encryption model, team sharing, CI.
  138. - [Migrating to the Vault](./docs/migrating-to-vault.md). From `env/` to `.hulak/`.
  139. - [Versioning Your Vault](./docs/versioning.md). Git workflow for secrets.
  140. - [Comparison](./docs/comparison.md). Hulak vs SOPS, Bruno, and friends.
  141. - [Request Body](./docs/body.md)
  142. - [Actions](./docs/actions.md)
  143. - [Environment Secrets (classic mode)](./docs/environment.md)
  144. - [Response Files](./docs/response.md)
  145. - [GraphQL Explorer](./docs/graphql-explorer.md)
  146. - [Auth 2.0](./docs/auth20.md)
  147. - [MCP Server](./docs/mcp.md). Expose your requests to AI agents.
  148. For the live command surface, run:
  149. ```bash
  150. hulak help
  151. hulak <command> --help
  152. ```
  153. ## Schema Support
  154. The Hulak schema is available in the [Schema Store](https://www.schemastore.org/), so editors that support Schema Store can automatically enable completion for `.hk.yaml` and `.hk.yml` files.
  155. You can also point your YAML language server directly at:
  156. ```text
  157. https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
  158. ```
  159. ## Contributing
  160. ```bash
  161. git clone https://github.com/xaaha/hulak.git
  162. cd hulak
  163. mise install
  164. ```
  165. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development workflow.
  166. ## Support the Project
  167. If Hulak is useful to you, open an issue, suggest a feature, send a pull request, or sponsor the project.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.