REST · GraphQL · OAuth
Quick Start • GraphQL Explorer • Project Layout • Documentation
--- ### Run one request, a whole directory, or stay interactive
```bash
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
Browse schemas from multiple endpoints. Search operations. Build queries interactively. Execute inline. Save generated files from the terminal.
## Quick Start
### 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:
```bash
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:
```bash
# 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)
```bash
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:
```bash
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:
```bash
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:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Run the request:
```bash
hulak run example-api.hk.yaml --env prod
```
### Prefer plaintext `env/*.env` files instead of encrypted secrets?
```bash
hulak init classic
```
Plaintext mode is fully supported. See [docs/environment.md](./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](./docs/store.md).
- **Plaintext:** secrets live in plaintext `env/*.env` files. Simpler, no encryption. Add `env/` to `.gitignore`. See [docs/environment.md](./docs/environment.md).
Running classic and want to switch? See [docs/migrating-to-vault.md](./docs/migrating-to-vault.md).
## Commands
| Command | Purpose | Read more |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | Execute request file(s) or a directory | [body.md](./docs/body.md), [actions.md](./docs/actions.md) |
| `gql` | GraphQL explorer TUI | [graphql-explorer.md](./docs/graphql-explorer.md) |
| `secrets` | Encrypted vault CRUD | [store.md](./docs/store.md) |
| `init` | Initialize a hulak project | [store.md](./docs/store.md) |
| `migrate` | Postman to hulak conversion | [migrating-to-vault.md](./docs/migrating-to-vault.md) |
| `example` | Scaffold sample request files | — |
| `doctor` | Check project health | — |
| `version` | Print version | — |
Run `hulak