xaaha/hulakEin leichtgewichtiger, dateibasierter CLI-API-Client mit age-verschlüsselten Secrets, erstklassiger GraphQL-Unterstützung und einem integrierten MCP-Server für KI-Agent-Workflows.
<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">
Dein Messenger im Terminal.
</h3>
<p align="center">
<a href="#quick-start">Schnellstart</a> •
<a href="#graphql-explorer">GraphQL Explorer</a> •
<a href="#project-layout">Projektstruktur</a> •
<a href="#documentation">Dokumentation</a>
</p>
---
### Führe eine Anfrage, ein ganzes Verzeichnis aus oder bleibe interaktiv
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
Hulak führt Anfragedateien direkt aus deinem Projekt aus. Es unterstützt die gleichzeitige Ausführung von Verzeichnissen. Wenn du einfach `hulak` ausführst, wird auf eine interaktive Auswahl zurückgegriffen.
### Dedizierter GraphQL Explorer
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
Durchsuche Schemas von mehreren Endpunkten. Suche Operationen. Erstelle Abfragen interaktiv. Führe sie inline aus. Speichere generierte Dateien aus dem Terminal.
## Schnellstart
### Installation
Hulak wird über [xaaha/tap](https://github.com/xaaha/homebrew-tap) bereitgestellt. Homebrew 6.0+ erfordert explizites Vertrauen für Drittanbieter-Taps; ohne dieses überspringt `brew upgrade` hulak stillschweigend. Einmaliger Schritt pro Maschine:
```bash
brew trust xaaha/tap
brew install --cask xaaha/tap/hulak
```
Weitere Installationsoptionen:
- `go install github.com/xaaha/hulak@latest`
- Aus dem Quellcode mit `go build -o hulak` bauen
#### 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:
```bash
# zsh
hulak completion zsh > "${fpath[1]}/_hulak" # dann Shell neu starten
# 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`.
### Weg A. API-Client mit verschlüsselten Secrets (Standard)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
Erstelle eine Beispielanfrage. Um schnell zu sehen, wie eine Anfragedatei aussieht, führe aus:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> Für andere Typen führe aus: `hulak example`. Der Unterbefehl `example` bietet dir eine schnelle Möglichkeit, eine Anfragedatei zu schreiben, die du anpassen kannst. Für weitere Informationen führe `hulak example -h` aus.
Um ein Secret einzurichten, kannst du ausführen:
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
Jetzt kannst du in deiner Datei `example-api.hk.yaml` auf dieses Secret verweisen:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Führe die Anfrage aus:
```bash
hulak run example-api.hk.yaml --env prod
```
### Bevorzugst du Klartext-`env/*.env`-Dateien anstelle verschlüsselter Secrets?
```bash
hulak init classic
```
Der Klartextmodus wird vollständig unterstützt. Weitere Informationen findest du in [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
## Verschlüsselter Secrets-Tresor oder Klartext-`.env`-Dateien
Hulak läuft in zwei Modi. Wähle einmal während `hulak init`. Du kannst später migrieren.
- **Tresor (Standard):** Secrets liegen in `.hulak/store.age`, verschlüsselt mit einem age- oder SSH-Schlüsselpaar. Sicher zum Committen. Teams teilen über eine Empfängerdatei. Siehe [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **Klartext:** Secrets liegen in Klartext-`env/*.env`-Dateien. Einfacher, keine Verschlüsselung. Füge `env/` zu `.gitignore` hinzu. Siehe [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
Du läufst im Classic-Modus und möchtest wechseln? Siehe [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## Nutzung aus einem KI-Agenten (MCP)
Hulak liefert einen integrierten [MCP](https://modelcontextprotocol.io)-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 einen Dry-Run von `login` gegen Staging aus", „rufe `getUser` auf und zeige die Antwort".
Für Claude Code füge ihn mit einem Befehl hinzu:
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
Cursor, Zed, Codex, opencode und Pi verwenden stattdessen eine kleine Konfigurationsdatei. Siehe [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) für jede einzelne.
Secrets verlassen niemals deinen Rechner: Der Agent arbeitet mit **Namen** von Anfragen und Umgebungen, niemals mit entschlüsselten Werten. Lesevorgänge und Dry-Runs sind schreibgeschützt; Schreibvorgänge werden schema-validiert; Antwortdateien werden nicht gespeichert, es sei denn, dies wird angefordert.
Vollständige Einrichtung, Tool-Referenz und Sicherheitsmodell: [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## Befehle
| Befehl | Zweck | Mehr erfahren |
| --------- | ---------------------------------------------- | ---------------------------------------------------------- |
| `run` | Anfragedatei(en) oder ein Verzeichnis ausführen | [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` | GraphQL-Explorer-TUI | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | CRUD für verschlüsselten Tresor | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | Ein Hulak-Projekt initialisieren | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Konvertierung von Postman zu Hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | Beispiel-Anfragedateien erstellen | — |
| `doctor` | Projektzustand prüfen | — |
| `mcp` | Anfragen über MCP für KI-Agenten bereitstellen | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | Version ausgeben | — |
Führe `hulak <command> --help` aus, um Flags und befehlsspezifische Beispiele zu erhalten.
### Verhalten der Auswahl
Das Weglassen von `--env` öffnet eine interaktive Auswahl.
- `hulak run` und `hulak gql` fragen nur nach, wenn Dateien auf `{{.key}}` verweisen.
- `hulak secrets`-Unterbefehle fragen jedes Mal nach (außer `secrets list`).
- Nicht-interaktive Shells erfordern `--env <name>`.
## Häufige Fallstricke
- **Committen Sie niemals `~/.config/hulak/identity.txt`.** Das ist Ihr privater Schlüssel. Modus 0600. Sichern Sie ihn zuerst. Siehe [docs/store.md#identity-backup](https://github.com/xaaha/hulak/blob/main/docs/store.md#identity-backup).
- **Bei `hulak init` erstellt `-env` Env-Dateien. Es ist ein Setup-Flag, kein Laufzeit-Selektor.** `hulak init -env staging prod` erstellt zwei Envs.
- **`env` ist ein Alias für `secrets`.** `hulak env list` funktioniert genauso wie `hulak secrets list`.
- **GUI-Editoren benötigen ein Wait-Flag für `secrets edit`.** Verwenden Sie `EDITOR="code -w"` oder `EDITOR="zed --wait"`. Ohne dieses kehrt der Editor sofort zurück und Änderungen gehen verloren.
- **Merge-Konflikte bei `store.age` erfordern ein Rezept.** Siehe [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## Projektstruktur
```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
Starte den Explorer mit einer Datei oder einem Verzeichnis:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
Lies die vollständige Anleitung in [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## Dokumentation
Beginne hier für die vollständige Referenz:
- [Verschlüsselter Store](https://github.com/xaaha/hulak/blob/main/docs/store.md). Verschlüsselungsmodell, Team-Sharing, CI.
- [Migration zum Tresor](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). Von `env/` zu `.hulak/`.
- [Versionierung deines Tresors](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). Git-Workflow für Secrets.
- [Vergleich](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak vs SOPS, Bruno und Freunde.
- [Anfrage-Body](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Aktionen](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Umgebungs-Secrets (Classic-Modus)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Antwortdateien](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). Stelle deine Anfragen KI-Agenten bereit.
Für die aktuelle Befehlsübersicht führe aus:
```bash
hulak help
hulak <command> --help
```
## Schema-Unterstützung
Das Hulak-Schema ist im [Schema Store](https://www.schemastore.org/) verfügbar, sodass Editoren, die den Schema Store unterstützen, die Vervollständigung für `.hk.yaml`- und `.hk.yml`-Dateien automatisch aktivieren können.
Du kannst deinen YAML Language Server auch direkt auf Folgendes verweisen:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## Mitwirken
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
Siehe [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md) für den vollständigen Entwicklungs-Workflow.
## Unterstütze das Projekt
Wenn Hulak für dich nützlich ist, eröffne ein Issue, schlage ein Feature vor, sende einen Pull Request oder sponse das Projekt.