xaaha/hulakUn client API CLI leggero basato su file con segreti crittografati con age, supporto GraphQL di prima classe e un server MCP integrato per i flussi di lavoro degli agenti AI.
<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">
Il tuo messenger nel terminale.
</h3>
<p align="center">
<a href="#quick-start">Avvio rapido</a> •
<a href="#graphql-explorer">GraphQL Explorer</a> •
<a href="#project-layout">Struttura del progetto</a> •
<a href="#documentation">Documentazione</a>
</p>
---
### Esegui una richiesta, un'intera directory o resta in modalità interattiva
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
Hulak esegue i file di richiesta direttamente dal tuo progetto. Supporta l'esecuzione concorrente delle directory. Torna a un selettore interattivo quando esegui semplicemente `hulak`.
### GraphQL Explorer dedicato
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
Esplora gli schemi da più endpoint. Cerca operazioni. Costruisci query in modo interattivo. Esegui inline. Salva i file generati dal terminale.
## Avvio rapido
### Installazione
Hulak è distribuito tramite [xaaha/tap](https://github.com/xaaha/homebrew-tap). Homebrew 6.0+ richiede un trust esplicito per i tap di terze parti; senza di esso, `brew upgrade` salta silenziosamente hulak. Passaggio una tantum per macchina:
```bash
brew trust xaaha/tap
brew install --cask xaaha/tap/hulak
```
Altre opzioni di installazione:
- `go install github.com/xaaha/hulak@latest`
- Compila dal sorgente con `go build -o hulak`
#### Completamento shell (go install / build dal sorgente)
Homebrew installa il completamento automaticamente. Se hai installato tramite `go install`
o compilato dal sorgente, attivalo una volta:
```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 richiede `autoload -Uz compinit && compinit` nel tuo `.zshrc`.
### Percorso A. Client API con segreti cifrati (predefinito)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
Genera una richiesta iniziale; per verificare rapidamente come appare un file di richiesta esegui:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> Per altri tipi esegui: `hulak example`. Il sottocomando `example` ti offre un modo rapido per scrivere un file di richiesta che puoi modificare. Per maggiori informazioni esegui `hulak example -h`
Per impostare un segreto puoi eseguire:
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
Ora, nel tuo file `example-api.hk.yaml`, puoi fare riferimento a questo segreto:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Esegui la richiesta:
```bash
hulak run example-api.hk.yaml --env prod
```
### Preferisci file `env/*.env` in chiaro invece dei segreti cifrati?
```bash
hulak init classic
```
La modalità in chiaro è pienamente supportata. Vedi [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md) per maggiori informazioni
## Vault di segreti cifrati o file `.env` in chiaro
Hulak funziona in due modalità. Scegline una durante `hulak init`. Puoi migrare in seguito.
- **Vault (predefinito):** i segreti risiedono in `.hulak/store.age`, cifrati con una coppia di chiavi age o SSH. Sicuro da committare. I team condividono tramite un file dei destinatari. Vedi [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **In chiaro:** i segreti risiedono in file `env/*.env` in chiaro. Più semplice, nessuna cifratura. Aggiungi `env/` a `.gitignore`. Vedi [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
Stai usando la modalità classic e vuoi passare all'altra? Vedi [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## Usalo da un agente AI (MCP)
Hulak include un server [MCP](https://modelcontextprotocol.io) integrato, così agenti come Claude Code, Cursor e Zed possono gestire la tua collezione di API in linguaggio naturale — "elenca le richieste", "dry-run di `login` su staging", "chiama `getUser` e mostra la risposta".
Per Claude Code, aggiungilo con un solo comando:
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
Cursor, Zed, Codex, opencode e Pi usano invece un piccolo file di configurazione. Vedi [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) per ciascuno.
I segreti non lasciano mai la tua macchina: l'agente lavora con i **nomi** delle richieste e degli ambienti, mai con i valori decifrati. Le letture e i dry-run sono di sola lettura; le scritture sono validate dallo schema; i file di risposta non vengono salvati se non richiesto.
Configurazione completa, riferimento degli strumenti e modello di sicurezza: [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## Comandi
| Comando | Scopo | Approfondisci |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | Esegue file di richiesta o una directory | [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 GraphQL explorer | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | CRUD del vault cifrato | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | Inizializza un progetto hulak | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Conversione da Postman a hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | Genera file di richiesta di esempio | — |
| `doctor` | Verifica la salute del progetto | — |
| `mcp` | Serve le richieste agli agenti AI via MCP | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | Stampa la versione | — |
Esegui `hulak <command> --help` per i flag e gli esempi per singolo comando.
### Comportamento del selettore
Omettere `--env` apre un selettore interattivo.
- `hulak run` e `hulak gql` chiedono solo quando i file fanno riferimento a `{{.key}}`.
- I sottocomandi di `hulak secrets` chiedono ogni volta (tranne `secrets list`).
- Le shell non interattive richiedono `--env <name>`.
## Insidie comuni
- **Non committare mai `~/.config/hulak/identity.txt`.** È la tua chiave privata. Modalità 0600. Fanne prima un backup. Vedi [docs/store.md#identity-backup](https://github.com/xaaha/hulak/blob/main/docs/store.md#identity-backup).
- **Su `hulak init`, `-env` crea i file env. È un flag di setup, non un selettore a runtime.** `hulak init -env staging prod` genera due ambienti.
- **`env` è un alias di `secrets`.** `hulak env list` funziona come `hulak secrets list`.
- **Gli editor GUI richiedono un flag di attesa per `secrets edit`.** Usa `EDITOR="code -w"` o `EDITOR="zed --wait"`. Senza di esso l'editor ritorna immediatamente e le modifiche vanno perse.
- **I conflitti di merge su `store.age` richiedono una procedura.** Vedi [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## Struttura del progetto
```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.
```
## GraphQL Explorer
Avvia l'explorer con un file o una directory:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
Leggi la guida completa in [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## Documentazione
Inizia da qui per il riferimento completo:
- [Encrypted Store](https://github.com/xaaha/hulak/blob/main/docs/store.md). Modello di cifratura, condivisione nel team, CI.
- [Migrating to the Vault](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). Da `env/` a `.hulak/`.
- [Versioning Your Vault](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). Flusso di lavoro Git per i segreti.
- [Comparison](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak vs SOPS, Bruno e simili.
- [Request Body](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Actions](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Environment Secrets (classic mode)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Response Files](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [GraphQL Explorer](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)
- [Auth 2.0](https://github.com/xaaha/hulak/blob/main/docs/auth20.md)
- [MCP Server](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). Espone le tue richieste agli agenti AI.
Per la superficie dei comandi live, esegui:
```bash
hulak help
hulak <command> --help
```
## Supporto dello schema
Lo schema di Hulak è disponibile nello [Schema Store](https://www.schemastore.org/), quindi gli editor che supportano lo Schema Store possono abilitare automaticamente il completamento per i file `.hk.yaml` e `.hk.yml`.
Puoi anche puntare direttamente il tuo language server YAML a:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## Contribuire
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
Vedi [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md) per il flusso di lavoro di sviluppo completo.
## Supporta il progetto
Se Hulak ti è utile, apri una issue, suggerisci una funzionalità, invia una pull request o sponsorizza il progetto.