xaaha/hulakUm cliente CLI de API leve, baseado em arquivos, com segredos criptografados com age, suporte GraphQL de primeira classe e um servidor MCP integrado para fluxos de trabalho de agentes de IA.
<p align="center">
<img alt="Hulak" src="https://raw.githubusercontent.com/xaaha/hulak/main/assets/hulak-logo.svg" width="180" />
</p>
<h1 align="center">Hulak</h1>
<h3 align="center">
Seu mensageiro no terminal.
</h3>
<p align="center">
<a href="#quick-start">Início Rápido</a> •
<a href="#graphql-explorer">Explorador GraphQL</a> •
<a href="#project-layout">Estrutura do Projeto</a> •
<a href="#documentation">Documentação</a>
</p>
---
### Execute uma requisição, um diretório inteiro ou permaneça interativo
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
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
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
Navegue por schemas de múltiplos endpoints. Pesquise operações. Construa consultas interativamente. Execute inline. Salve arquivos gerados a partir do terminal.
## Início Rápido
### Instalação
O Hulak é distribuído via [xaaha/tap](https://github.com/xaaha/homebrew-tap). O Homebrew 6.0+ exige confiança explícita para taps de terceiros; sem isso, o `brew upgrade` ignora o hulak silenciosamente. Etapa única por máquina:
```bash
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`
#### Autocompletar do shell (go install / compilações a partir do código-fonte)
O Homebrew instala o autocompletar automaticamente. Se você instalou via `go install`
ou compilou a partir do código-fonte, ative uma vez:
```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
```
O Zsh exige `autoload -Uz compinit && compinit` no seu `.zshrc`.
### Caminho A. Cliente de API com segredos criptografados (padrão)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
Crie um modelo de requisição inicial; para verificar rapidamente como um arquivo de requisição se parece, execute:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> Para outros tipos, execute: `hulak example`. O subcomando `example` oferece 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:
```bash
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:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Execute a requisição:
```bash
hulak run example-api.hk.yaml --env prod
```
### Prefere arquivos `env/*.env` em texto simples em vez de segredos criptografados?
```bash
hulak init classic
```
O modo texto simples é totalmente suportado. Consulte [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md) para mais informações
## Cofre de Segredos Criptografados ou arquivos `.env` em texto simples
O Hulak opera em dois modos. Escolha uma vez durante o `hulak init`. Você pode migrar depois.
- **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](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **Texto simples:** os segredos ficam em arquivos `env/*.env` em texto simples. Mais simples, sem criptografia. Adicione `env/` ao `.gitignore`. Consulte [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
Usando o modo classic e quer trocar? Consulte [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## Use a partir de um agente de IA (MCP)
O Hulak inclui um servidor [MCP](https://modelcontextprotocol.io) integrado, para que agentes como Claude Code, Cursor e Zed possam conduzir sua coleção de APIs em linguagem natural — "liste as requisições", "simule `login` contra staging", "chame `getUser` e mostre a resposta".
Para o Claude Code, adicione-o com um comando:
```bash
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](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) para cada um.
Os segredos nunca saem da sua máquina: o agente trabalha com **nomes** de requisições e ambientes, nunca com valores descriptografados. Leituras e simulações são somente leitura; escritas são validadas por schema; 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](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## Comandos
| Comando | Propósito | Leia mais |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | Executa arquivo(s) de requisição ou um diretório | [body.md](https://github.com/xaaha/hulak/blob/main/docs/body.md), [actions.md](https://github.com/xaaha/hulak/blob/main/docs/actions.md) |
| `gql` | TUI do explorador GraphQL | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | CRUD do cofre criptografado | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | Inicializa um projeto hulak | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Conversão de Postman para hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | Cria arquivos de requisição de exemplo | — |
| `doctor` | Verifica a saúde do projeto | — |
| `mcp` | Serve requisições para agentes de IA via MCP | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | Imprime a versão | — |
Execute `hulak <command> --help` para 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 sempre (exceto `secrets list`).
- Shells não interativos exigem `--env <name>`.
## Armadilhas Comuns
- **Nunca faça commit de `~/.config/hulak/identity.txt`.** Essa é sua chave privada. Modo 0600. Faça backup primeiro. Consulte [docs/store.md#identity-backup](https://github.com/xaaha/hulak/blob/main/docs/store.md#identity-backup).
- **No `hulak init`, `-env` cria arquivos de ambiente. É uma flag de configuração, não um seletor de tempo de execução.** `hulak init -env staging prod` cria dois ambientes.
- **`env` é um alias para `secrets`.** `hulak env list` funciona da mesma forma que `hulak secrets list`.
- **Editores com GUI precisam de uma flag de espera para `secrets edit`.** Use `EDITOR="code -w"` ou `EDITOR="zed --wait"`. Sem isso, o editor retorna imediatamente e as alterações são perdidas.
- **Conflitos de merge em `store.age` precisam de uma receita.** Consulte [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## Estrutura do projeto
```text
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:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
Leia o guia completo em [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## Documentação
Comece aqui para a referência completa:
- [Cofre Criptografado](https://github.com/xaaha/hulak/blob/main/docs/store.md). Modelo de criptografia, compartilhamento em equipe, CI.
- [Migrando para o Cofre](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). De `env/` para `.hulak/`.
- [Versionando Seu Cofre](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). Fluxo de trabalho Git para segredos.
- [Comparação](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak vs SOPS, Bruno e similares.
- [Corpo da Requisição](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Ações](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Segredos de Ambiente (modo classic)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Arquivos de Resposta](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [Explorador GraphQL](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)
- [Auth 2.0](https://github.com/xaaha/hulak/blob/main/docs/auth20.md)
- [Servidor MCP](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). Exponha suas requisições para agentes de IA.
Para a superfície de comandos ao vivo, execute:
```bash
hulak help
hulak <command> --help
```
## Suporte a Schema
O schema do Hulak está disponível no [Schema Store](https://www.schemastore.org/), então editores que suportam o Schema Store podem habilitar automaticamente o autocompletar para arquivos `.hk.yaml` e `.hk.yml`.
Você também pode apontar seu servidor de linguagem YAML diretamente para:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## Contribuindo
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
Consulte [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md) para o fluxo de trabalho completo de desenvolvimento.
## Apoie o Projeto
Se o Hulak é útil para você, abra uma issue, sugira um recurso, envie um pull request ou patrocine o projeto.