_{REST · GraphQL · OAuth}

Quick Start • GraphQL Explorer • Project Layout • Documentation

hulak run ./requests/

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.

Browse schemas from multiple endpoints. Search operations. Build queries interactively. Execute inline. Save generated files from the terminal.

brew install xaaha/tap/hulak

Other install options:

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

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

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

hulak init classic

Plaintext mode is fully supported. See docs/environment.md for more info

Hulak runs in two modes. Pick once during hulak init. You can migrate later.

• 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.
• Plaintext: secrets live in plaintext env/*.env files. Simpler, no encryption. Add env/ to .gitignore. See docs/environment.md.

Running classic and want to switch? See docs/migrating-to-vault.md.

Run hulak <command> --help for flags and per-command examples.

Omitting --env opens an interactive picker.

• hulak run and hulak gql only prompt when files reference {{.key}}.
• hulak secrets subcommands prompt every time (except secrets list).
• Non-interactive shells require --env <name>.

• Never commit ~/.config/hulak/identity.txt. That is your private key. Mode 0600. Back it up first. See docs/store.md#identity-backup.
• On hulak init, -env creates env files. It is a setup flag, not a runtime selector. hulak init -env staging prod scaffolds two envs.
• env is an alias for secrets. hulak env list works the same as hulak secrets list.
• 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.
• Merge conflicts on store.age need a recipe. See 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.

Start the explorer with a file or a directory:

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

Read the full guide in docs/graphql-explorer.md.

Start here for the full reference:

• Encrypted Store. Encryption model, team sharing, CI.
• Migrating to the Vault. From env/ to .hulak/.
• Versioning Your Vault. Git workflow for secrets.
• Comparison. Hulak vs SOPS, Bruno, and friends.
• Request Body
• Actions
• Environment Secrets (classic mode)
• Response Files
• GraphQL Explorer
• Auth 2.0

For the live command surface, run:

hulak help
hulak <command> --help

The Hulak schema is available in the Schema Store, so editors that support Schema Store can automatically enable completion for .hk.yaml and .hk.yml files.

You can also point your YAML language server directly at:

https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json

git clone https://github.com/xaaha/hulak.git
cd hulak
mise install

See CONTRIBUTING.md for the full development workflow.

If Hulak is useful to you, open an issue, suggest a feature, send a pull request, or sponsor the project.