hulak

Cliente de API nativo do Git com segredos criptografados.

_{REST · GraphQL · OAuth}

Início Rápido • Explorador GraphQL • Estrutura do Projeto • Documentação

Execute uma requisição, um diretório inteiro, ou permaneça no modo interativo

hulak run ./requests/

O Hulak executa arquivos de requisição diretamente do seu projeto. Ele suporta execução concorrente de diretórios. Ele recorre a um seletor interativo quando você simplesmente executa hulak.

Explorador GraphQL dedicado

Navegue por esquemas de vários endpoints. Pesquise operações. Construa consultas interativamente. Execute inline. Salve os arquivos gerados a partir do terminal.

Início Rápido

Instalação

O Hulak é distribuído via xaaha/tap. O Homebrew 6.0+ exige confiança explícita para taps de terceiros; sem isso, o brew upgrade pula o hulak silenciosamente. Etapa única por máquina:

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

Outras opções de instalação:

• go install github.com/xaaha/hulak@latest
• Compile a partir do código-fonte com go build -o hulak

Auto-completar no shell (go install / compilações a partir do código-fonte)

O Homebrew instala o auto-completar automaticamente. Se você instalou via go install ou compilou a partir do código-fonte, ative-o uma vez:

# 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

O Zsh exige autoload -Uz compinit && compinit no seu .zshrc.

Caminho A. Cliente de API com segredos criptografados (padrão)

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

Gere uma requisição inicial. Para verificar rapidamente a aparência de um arquivo de requisição, execute:

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

[!Note] Para outros tipos, execute: hulak example. O subcomando example fornece uma maneira rápida de escrever um arquivo de requisição que você pode modificar. Para mais informações, execute hulak example -h

Para configurar um segredo, você pode executar:

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

Agora, no seu arquivo example-api.hk.yaml, você pode referenciar este segredo:

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

Execute a requisição:

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

Prefere arquivos env/*.env em texto puro em vez de segredos criptografados?

hulak init classic

O modo texto puro é totalmente suportado. Consulte docs/environment.md para mais informações.

Cofre de Segredos Criptografados ou Arquivos .env em Texto Puro

O Hulak opera em dois modos. Escolha uma vez durante o hulak init. Você pode migrar posteriormente.

• Cofre (padrão): os segredos ficam em .hulak/store.age, criptografados com um par de chaves age ou SSH. Seguro para commit. Equipes compartilham via um arquivo de destinatários. Consulte docs/store.md.
• Texto puro: os segredos ficam em arquivos env/*.env em texto puro. Mais simples, sem criptografia. Adicione env/ ao .gitignore. Consulte docs/environment.md.

Está no modo clássico e quer mudar? Consulte docs/migrating-to-vault.md.

Use-o a partir de um agente de IA (MCP)

O Hulak acompanha um servidor MCP integrado, permitindo que agentes como Claude Code, Cursor e Zed controlem sua coleção de APIs em linguagem natural — "liste as requisições", "faça um dry-run de login no staging", "chame getUser e mostre a resposta".

Para o Claude Code, adicione-o com um único comando:

claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests

Cursor, Zed, Codex, opencode e Pi usam um pequeno arquivo de configuração. Consulte docs/mcp.md para cada um.

Os segredos nunca saem da sua máquina: o agente trabalha com nomes de requisição e de ambiente, nunca com valores descriptografados. Leituras e dry-runs são somente leitura; gravações são validadas por esquema; arquivos de resposta não são salvos a menos que solicitado.

Configuração completa, referência de ferramentas e modelo de segurança: docs/mcp.md.

Comandos

Execute hulak <command> --help para ver as flags e exemplos por comando.

Comportamento do seletor

Omitir --env abre um seletor interativo.

• hulak run e hulak gql só solicitam quando os arquivos referenciam {{.key}}.
• Os subcomandos de hulak secrets solicitam todas as vezes (exceto secrets list).
• Shells não interativos exigem --env <name>.

Armadilhas Comuns

• Nunca faça commit de ~/.config/hulak/identity.txt. Essa é a sua chave privada. Modo 0600. Faça backup primeiro. Consulte docs/store.md#identity-backup.
• No hulak init, -env cria arquivos de ambiente. É uma flag de configuração, não um seletor de execução. hulak init -env staging prod gera dois ambientes.
• env é um alias para secrets. hulak env list funciona igual a hulak secrets list.
• Editores GUI precisam de uma flag de espera para secrets edit. Use EDITOR="code -w" ou EDITOR="zed --wait". Sem ela, o editor retorna imediatamente e as alterações são perdidas.
• Conflitos de merge em store.age precisam de uma receita. Consulte .

Estrutura do Projeto

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.

Explorador GraphQL

Inicie o explorador com um arquivo ou um diretório:

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

Leia o guia completo em docs/graphql-explorer.md.

Documentação

Comece aqui para a referência completa:

• Cofre Criptografado. Modelo de criptografia, compartilhamento em equipe, CI.
• Migrando para o Cofre. De env/ para .hulak/.
• Versionando Seu Cofre. Fluxo de trabalho Git para segredos.
• Comparação. Hulak vs SOPS, Bruno e outros.
• Corpo da Requisição
• Ações
• Segredos de Ambiente (modo clássico)
• Arquivos de Resposta
• Explorador GraphQL
• Auth 2.0
• Servidor MCP. Exponha suas requisições a agentes de IA.

Para a lista completa de comandos, execute:

hulak help
hulak <command> --help

Suporte a Esquemas

O esquema do Hulak está disponível no Schema Store, para que editores que suportam o Schema Store possam ativar automaticamente o autocompletar para arquivos .hk.yaml e .hk.yml.

Você também pode apontar seu servidor de linguagem YAML diretamente para:

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

Contribuindo

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

Consulte CONTRIBUTING.md para o fluxo de desenvolvimento completo.

Apoie o Projeto

Se o Hulak é útil para você, abra uma issue, sugira um recurso, envie um pull request ou patrocine o projeto.