hulak

Client API nativo Git con segreti crittografati.

_{REST · GraphQL · OAuth}

Avvio rapido • Esploratore GraphQL • Struttura del progetto • Documentazione

Esegui una richiesta, un'intera directory o resta in modalità interattiva

hulak run ./requests/

Hulak esegue i file di richiesta direttamente dal tuo progetto. Supporta l'esecuzione concorrente di directory. Se esegui semplicemente hulak, passa automaticamente a un selettore interattivo.

Esploratore GraphQL dedicato

Sfoglia gli schemi di più endpoint. Cerca operazioni. Costruisci query in modo interattivo. Esegui inline. Salva i file generati dal terminale.

Avvio rapido

Installazione

Hulak viene distribuito tramite xaaha/tap. Homebrew 6.0+ richiede un livello di fiducia esplicito per i tap di terze parti; senza questo, brew upgrade salta silenziosamente hulak. Operazione una tantum per macchina:

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:

# 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 crittografati (predefinito)

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

Genera una richiesta iniziale; per verificare rapidamente come è fatto un file di richiesta, esegui:

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 configurare un segreto puoi eseguire:

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:

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

Esegui la richiesta:

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

Preferisci file env/*.env in chiaro invece dei segreti crittografati?

hulak init classic

La modalità in chiaro è pienamente supportata. Vedi docs/environment.md per maggiori informazioni

Vault dei segreti crittografati oppure file .env in chiaro

Hulak funziona in due modalità. Scegli una volta durante hulak init. Puoi migrare in seguito.

• Vault (predefinito): i segreti sono in .hulak/store.age, crittografati con una coppia di chiavi age o SSH. Sicuri da committare. I team li condividono tramite un file dei destinatari. Vedi docs/store.md.
• Testo in chiaro: i segreti sono in file env/*.env in chiaro. Più semplice, nessuna crittografia. Aggiungi env/ al .gitignore. Vedi docs/environment.md.

Usi la modalità classica e vuoi cambiare? Vedi docs/migrating-to-vault.md.

Usalo da un agente AI (MCP)

Hulak include un server MCP integrato, così agenti come Claude Code, Cursor e Zed possono pilotare la tua raccolta API in linguaggio naturale — "elenca le richieste", "dry-run login verso staging", "chiama getUser e mostra la risposta".

Per Claude Code, aggiungilo con un comando:

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

I segreti non lasciano mai la tua macchina: l'agente lavora con i nomi di richieste e ambienti, mai con i valori decrittati. Letture e dry-run sono in sola lettura; le scritture sono validate tramite schema; i file di risposta non vengono salvati se non richiesto.

Configurazione completa, riferimento degli strumenti e modello di sicurezza: docs/mcp.md.

Comandi

Esegui hulak <command> --help per le opzioni e gli esempi di ciascun comando.

Comportamento del selettore

Se ometti --env, viene aperto un selettore interattivo.

• hulak run e hulak gql mostrano un prompt solo quando i file fanno riferimento a {{.key}}.
• I sottocomandi di hulak secrets mostrano sempre un prompt (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. Fai prima un backup. Vedi docs/store.md#identity-backup.
• Durante hulak init, -env crea i file degli ambienti. È un flag di configurazione, non un selettore 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, l'editor restituisce subito e le modifiche vanno perse.
• I conflitti di merge su store.age richiedono una procedura specifica. Vedi .

Struttura del progetto

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.

Esploratore GraphQL

Avvia l'esploratore con un file o una directory:

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

Leggi la guida completa in docs/graphql-explorer.md.

Documentazione

Inizia qui per il riferimento completo:

• Store crittografato. Modello di crittografia, condivisione nel team, CI.
• Migrazione al Vault. Da env/ a .hulak/.
• Versionamento del Vault. Flusso di lavoro Git per i segreti.
• Confronto. Hulak vs SOPS, Bruno e affini.
• Corpo della richiesta
• Azioni
• Segreti d'ambiente (modalità classica)
• File di risposta
• Esploratore GraphQL
• Auth 2.0
• Server MCP. Esponi le tue richieste agli agenti AI.

Per la superficie completa dei comandi, esegui:

hulak help
hulak <command> --help

Supporto per gli schemi

Lo schema Hulak è disponibile nello Schema Store, quindi gli editor che supportano Schema Store possono abilitare automaticamente il completamento per i file .hk.yaml e .hk.yml.

Puoi anche puntare il tuo language server YAML direttamente a:

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

Contributi

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

Vedi CONTRIBUTING.md per il flusso di sviluppo completo.

Sostieni il progetto

Se Hulak ti è utile, apri una issue, suggerisci una funzionalità, invia una pull request o sponsorizza il progetto.