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

Comando	Scopo	Approfondisci
run	Esegue file di richiesta o una directory	body.md, actions.md
gql	Esploratore GraphQL TUI	graphql-explorer.md
secrets	CRUD del vault crittografato	store.md
init	Inizializza un progetto hulak	store.md
migrate	Conversione da Postman a hulak	migrating-to-vault.md
example	Genera file di richiesta di esempio	—
doctor	Controlla lo stato del progetto	—
mcp	Serve richieste ad agenti AI tramite MCP	mcp.md
version	Mostra la versione	—

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