xaaha/hulakUn client API CLI léger basé sur des fichiers, avec des secrets chiffrés par age, une prise en charge GraphQL native et un serveur MCP intégré pour les workflows d'agents IA.
<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">
Votre messager dans le terminal.
</h3>
<p align="center">
<a href="#quick-start">Démarrage rapide</a> •
<a href="#graphql-explorer">Explorateur GraphQL</a> •
<a href="#project-layout">Structure du projet</a> •
<a href="#documentation">Documentation</a>
</p>
---
### Exécutez une requête, un répertoire entier, ou restez en interactif
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
Hulak exécute les fichiers de requête directement depuis votre projet. Il prend en charge l'exécution concurrente de répertoires. Il bascule vers un sélecteur interactif lorsque vous lancez simplement `hulak`.
### Explorateur GraphQL dédié
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
Parcourez les schémas de plusieurs endpoints. Recherchez des opérations. Construisez des requêtes de manière interactive. Exécutez en ligne. Enregistrez les fichiers générés depuis le terminal.
## Démarrage rapide
### Installation
Hulak est distribué via [xaaha/tap](https://github.com/xaaha/homebrew-tap). Homebrew 6.0+ exige une confiance explicite pour les taps tiers ; sans cela, `brew upgrade` ignore silencieusement hulak. Étape unique par machine :
```bash
brew trust xaaha/tap
brew install --cask xaaha/tap/hulak
```
Autres options d'installation :
- `go install github.com/xaaha/hulak@latest`
- Compiler depuis les sources avec `go build -o hulak`
#### Complétion shell (go install / compilations depuis les sources)
Homebrew installe la complétion automatiquement. Si vous avez installé via `go install`
ou compilé depuis les sources, activez-la une fois :
```bash
# zsh
hulak completion zsh > "${fpath[1]}/_hulak" # puis redémarrez votre 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 nécessite `autoload -Uz compinit && compinit` dans votre `.zshrc`.
### Voie A. Client API avec secrets chiffrés (par défaut)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
Générez une requête de démarrage ; pour vérifier rapidement à quoi ressemble un fichier de requête, exécutez :
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> Pour d'autres types, exécutez : `hulak example`. La sous-commande `example` vous offre un moyen rapide d'écrire un fichier de requête que vous pouvez modifier. Pour plus d'informations, exécutez `hulak example -h`
Pour configurer un secret, vous pouvez exécuter :
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
Maintenant, dans votre fichier `example-api.hk.yaml`, vous pouvez référencer ce secret :
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Exécutez la requête :
```bash
hulak run example-api.hk.yaml --env prod
```
### Vous préférez les fichiers `env/*.env` en clair plutôt que les secrets chiffrés ?
```bash
hulak init classic
```
Le mode en clair est entièrement pris en charge. Consultez [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md) pour plus d'informations
## Coffre de secrets chiffrés ou fichiers `.env` en clair
Hulak fonctionne selon deux modes. Choisissez-en un lors de `hulak init`. Vous pouvez migrer plus tard.
- **Coffre (par défaut) :** les secrets résident dans `.hulak/store.age`, chiffrés avec une paire de clés age ou SSH. Sûr à committer. Les équipes partagent via un fichier de destinataires. Consultez [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **En clair :** les secrets résident dans des fichiers `env/*.env` en clair. Plus simple, sans chiffrement. Ajoutez `env/` à `.gitignore`. Consultez [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
Vous utilisez le mode classic et souhaitez basculer ? Consultez [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## Utilisation depuis un agent IA (MCP)
Hulak embarque un serveur [MCP](https://modelcontextprotocol.io) intégré, afin que des agents comme Claude Code, Cursor et Zed puissent piloter votre collection d'API en langage naturel — « liste les requêtes », « dry-run `login` contre staging », « appelle `getUser` et affiche la réponse ».
Pour Claude Code, ajoutez-le avec une seule commande :
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
Cursor, Zed, Codex, opencode et Pi utilisent plutôt un petit fichier de configuration. Consultez [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) pour chacun.
Les secrets ne quittent jamais votre machine : l'agent travaille avec les **noms** de requêtes et d'environnements, jamais avec les valeurs déchiffrées. Les lectures et dry-runs sont en lecture seule ; les écritures sont validées par schéma ; les fichiers de réponse ne sont pas enregistrés sauf demande explicite.
Configuration complète, référence des outils et modèle de sécurité : [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## Commandes
| Commande | Objectif | En savoir plus |
| --------- | ---------------------------------------------- | ----------------------------------------------------------- |
| `run` | Exécuter un ou des fichiers de requête ou un répertoire | [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 de l'explorateur GraphQL | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | CRUD du coffre chiffré | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | Initialiser un projet hulak | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Conversion Postman vers hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | Générer des fichiers de requête d'exemple | — |
| `doctor` | Vérifier la santé du projet | — |
| `mcp` | Servir les requêtes aux agents IA via MCP | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | Afficher la version | — |
Exécutez `hulak <command> --help` pour les options et des exemples par commande.
### Comportement du sélecteur
Omettre `--env` ouvre un sélecteur interactif.
- `hulak run` et `hulak gql` ne demandent une saisie que lorsque des fichiers référencent `{{.key}}`.
- Les sous-commandes `hulak secrets` demandent une saisie à chaque fois (sauf `secrets list`).
- Les shells non interactifs nécessitent `--env <name>`.
## Pièges courants
- **Ne committez jamais `~/.config/hulak/identity.txt`.** C'est votre clé privée. Mode 0600. Sauvegardez-la d'abord. Consultez [docs/store.md#identity-backup](https://github.com/xaaha/hulak/blob/main/docs/store.md#identity-backup).
- **Lors de `hulak init`, `-env` crée des fichiers d'environnement. C'est un indicateur de configuration, pas un sélecteur d'exécution.** `hulak init -env staging prod` génère deux environnements.
- **`env` est un alias de `secrets`.** `hulak env list` fonctionne comme `hulak secrets list`.
- **Les éditeurs GUI nécessitent une option d'attente pour `secrets edit`.** Utilisez `EDITOR="code -w"` ou `EDITOR="zed --wait"`. Sans cela, l'éditeur rend la main immédiatement et les modifications sont perdues.
- **Les conflits de fusion sur `store.age` nécessitent une procédure.** Consultez [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## Structure du projet
```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.
```
## Explorateur GraphQL
Démarrez l'explorateur avec un fichier ou un répertoire :
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
Consultez le guide complet dans [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## Documentation
Commencez ici pour la référence complète :
- [Coffre chiffré](https://github.com/xaaha/hulak/blob/main/docs/store.md). Modèle de chiffrement, partage en équipe, CI.
- [Migration vers le coffre](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). De `env/` vers `.hulak/`.
- [Versionner votre coffre](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). Flux de travail Git pour les secrets.
- [Comparaison](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak vs SOPS, Bruno et compagnie.
- [Corps de requête](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Actions](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Secrets d'environnement (mode classic)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Fichiers de réponse](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [Explorateur GraphQL](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)
- [Auth 2.0](https://github.com/xaaha/hulak/blob/main/docs/auth20.md)
- [Serveur MCP](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). Exposez vos requêtes aux agents IA.
Pour la surface de commandes en direct, exécutez :
```bash
hulak help
hulak <command> --help
```
## Prise en charge du schéma
Le schéma Hulak est disponible dans le [Schema Store](https://www.schemastore.org/), de sorte que les éditeurs prenant en charge le Schema Store peuvent activer automatiquement la complétion pour les fichiers `.hk.yaml` et `.hk.yml`.
Vous pouvez également pointer directement votre serveur de langage YAML vers :
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## Contribuer
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
Consultez [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md) pour le flux de développement complet.
## Soutenir le projet
Si Hulak vous est utile, ouvrez une issue, suggérez une fonctionnalité, envoyez une pull request ou sponsorisez le projet.