Home
Softono
hulak

hulak

Open source MIT Go
GitHub
85
Stars
6
Forks
27
Issues
1
Watchers
2 weeks
Last Commit
API Tools Secret Management Terminal & CLI Tools

About hulak

Lightweight file-based CLI API client with encrypted secrets and first-class GraphQL support.

Platforms

Web Self-hosted

Languages

Go

Links

Source Code
x
Published by
xaaha
Visit View Profile

README.md

View on GitHub

Hulak

Git-native API client with encrypted secrets.

REST · GraphQL · OAuth

Quick Start • GraphQL Explorer • Project Layout • Documentation

Run one request, a whole directory, or stay interactive

Concurrent Execution 
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.

Dedicated GraphQL Explorer

GraphQL Explorer

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

Quick Start

Install

brew install xaaha/tap/hulak

Other install options:

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

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 for more info

Encrypted Secrets Vault Or Plaintext .env files

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.

Commands

Command Purpose Read more
run Execute request file(s) or a directory body.md, actions.md
gql GraphQL explorer TUI graphql-explorer.md
secrets Encrypted vault CRUD store.md
init Initialize a hulak project store.md
migrate Postman to hulak conversion migrating-to-vault.md
example Scaffold sample request files —
doctor Check project health —
version Print version —

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

Picker behavior

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>.

Common Pitfalls

  • 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.

Project layout

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 Explorer

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.

Documentation

Start here for the full reference:

For the live command surface, run:

hulak help
hulak <command> --help

Schema Support

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

Contributing

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

See CONTRIBUTING.md for the full development workflow.

Support the Project

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