hulak

Git-nativer API-Client mit verschlüsselten Geheimnissen.

_{REST · GraphQL · OAuth}

Schnellstart • GraphQL-Explorer • Projektstruktur • Dokumentation

Führe eine Anfrage, ein ganzes Verzeichnis aus – oder bleib interaktiv

hulak run ./requests/

Hulak führt Anfragedateien direkt aus deinem Projekt aus. Es unterstützt die gleichzeitige Ausführung von Verzeichnissen. Wenn du nur hulak ausführst, wird ein interaktiver Auswahldialog geöffnet.

Dedizierter GraphQL-Explorer

Durchstöbere Schemas mehrerer Endpunkte. Suche Operationen. Erstelle Abfragen interaktiv. Führe sie direkt aus. Speichere generierte Dateien aus dem Terminal.

Schnellstart

Installation

Hulak wird über xaaha/tap ausgeliefert. Homebrew 6.0+ verlangt explizites Vertrauen für Drittanbieter-Taps; ohne dieses überspringt brew upgrade hulak stillschweigend. Einmaliger Schritt pro Rechner:

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

Weitere Installationsoptionen:

• go install github.com/xaaha/hulak@latest
• Aus dem Quellcode bauen mit go build -o hulak

Shell-Vervollständigung (go install / Quellcode-Builds)

Homebrew installiert die Vervollständigung automatisch. Wenn du über go install installiert oder aus dem Quellcode gebaut hast, aktiviere sie einmalig:

# 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 erfordert autoload -Uz compinit && compinit in deiner .zshrc.

Pfad A. API-Client mit verschlüsselten Geheimnissen (Standard)

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

Erzeuge eine Starter-Anfrage. Um schnell zu sehen, wie eine Anfragedatei aussieht, führe Folgendes aus:

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

[!Note] Für andere Typen führe hulak example aus. Der Unterbefehl example bietet dir eine schnelle Möglichkeit, eine anpassbare Anfragedatei zu erstellen. Weitere Informationen erhältst du mit hulak example -h.

Um ein Geheimnis einzurichten, kannst du Folgendes ausführen:

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

In deiner Datei example-api.hk.yaml kannst du dieses Geheimnis nun referenzieren:

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

Führe die Anfrage aus:

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

Bevorzugst du Klartext-Dateien env/*.env anstelle verschlüsselter Geheimnisse?

hulak init classic

Der Klartextmodus wird vollständig unterstützt. Weitere Informationen findest du unter docs/environment.md.

Verschlüsselter Secrets-Vault oder Klartext-.env-Dateien

Hulak läuft in zwei Modi. Wähle einmal während hulak init. Du kannst später migrieren.

• Vault (Standard): Geheimnisse liegen in .hulak/store.age, verschlüsselt mit einem age- oder SSH-Schlüsselpaar. Bedenkenlos committbar. Teams teilen sie über eine Recipients-Datei. Siehe docs/store.md.
• Klartext: Geheimnisse liegen in Klartextdateien env/*.env. Einfacher, keine Verschlüsselung. Füge env/ zu .gitignore hinzu. Siehe docs/environment.md.

Du nutzt den klassischen Modus und möchtest wechseln? Siehe docs/migrating-to-vault.md.

Nutzung über einen KI-Agenten (MCP)

Hulak bringt einen integrierten MCP-Server mit, sodass Agenten wie Claude Code, Cursor und Zed deine API-Sammlung in natürlicher Sprache steuern können – „liste die Anfragen auf“, „führe login gegen Staging als Probelauf aus“, „rufe getUser auf und zeige die Antwort“.

Für Claude Code fügst du es mit einem Befehl hinzu:

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

Cursor, Zed, Codex, opencode und Pi verwenden stattdessen eine kleine Konfigurationsdatei. Details für jedes findest du in docs/mcp.md.

Geheimnisse verlassen deinen Rechner nie: Der Agent arbeitet mit Namen von Anfragen und Umgebungen, niemals mit entschlüsselten Werten. Lesezugriffe und Probeläufe sind schreibgeschützt; Schreibvorgänge werden schema-validiert; Antwortdateien werden nur auf Anfrage gespeichert.

Vollständige Einrichtung, Tool-Referenz und Sicherheitsmodell: docs/mcp.md.

Befehle

Führe hulak <command> --help aus, um Flags und Beispiele pro Befehl zu sehen.

Verhalten des Auswahldialogs

Wenn du --env weglässt, öffnet sich ein interaktiver Auswahldialog.

• hulak run und hulak gql fragen nur nach, wenn Dateien {{.key}} referenzieren.
• Unterbefehle von hulak secrets fragen jedes Mal nach (außer secrets list).
• Nicht-interaktive Shells erfordern --env <name>.

Häufige Fallstricke

• Commite niemals ~/.config/hulak/identity.txt. Das ist dein privater Schlüssel. Modus 0600. Sichere ihn zuerst. Siehe docs/store.md#identity-backup.
• Bei hulak init erstellt -env Umgebungsdateien. Es ist ein Einrichtungs-Flag, kein Laufzeit-Selektor. hulak init -env staging prod erzeugt zwei Umgebungen.
• env ist ein Alias für secrets. hulak env list funktioniert genauso wie hulak secrets list.
• GUI-Editoren benötigen für secrets edit ein Warte-Flag. Verwende EDITOR="code -w" oder EDITOR="zed --wait". Ohne dieses Flag kehrt der Editor sofort zurück und Änderungen gehen verloren.
• Merge-Konflikte bei benötigen ein Rezept. Siehe .

Projektstruktur

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

Starte den Explorer mit einer Datei oder einem Verzeichnis:

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

Die vollständige Anleitung findest du in docs/graphql-explorer.md.

Dokumentation

Hier beginnt die vollständige Referenz:

• Verschlüsselter Store. Verschlüsselungsmodell, Team-Freigabe, CI.
• Migration zum Vault. Von env/ zu .hulak/.
• Versionierung deines Vaults. Git-Workflow für Geheimnisse.
• Vergleich. Hulak vs. SOPS, Bruno und Verwandte.
• Anfrage-Body
• Aktionen
• Umgebungs-Geheimnisse (Klassikmodus)
• Antwortdateien
• GraphQL-Explorer
• Auth 2.0
• MCP-Server. Stelle deine Anfragen KI-Agenten bereit.

Für die vollständige Befehlsübersicht führe Folgendes aus:

hulak help
hulak <command> --help

Schema-Unterstützung

Das Hulak-Schema ist im Schema Store verfügbar. Editoren, die den Schema Store unterstützen, können so automatisch die Vervollständigung für .hk.yaml- und .hk.yml-Dateien aktivieren.

Du kannst deinen YAML-Sprachserver auch direkt auf folgende Adresse ausrichten:

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

Mitwirken

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

Den vollständigen Entwicklungs-Workflow findest du in CONTRIBUTING.md.

Unterstütze das Projekt

Wenn dir Hulak nützlich ist, erstelle ein Issue, schlage eine Funktion vor, sende einen Pull-Request oder sponsere das Projekt.