hulak

Client API natif Git avec secrets chiffrés.

_{REST · GraphQL · OAuth}

Démarrage rapide • Explorateur GraphQL • Structure du projet • Documentation

Exécutez une requête, tout un répertoire, ou restez en mode interactif

hulak run ./requests/

Hulak exécute les fichiers de requêtes directement depuis votre projet. Il prend en charge l'exécution concurrente d'un répertoire. Il bascule vers un sélecteur interactif lorsque vous lancez simplement hulak.

Explorateur GraphQL dédié

Parcourez les schémas de plusieurs points de terminaison. Recherchez des opérations. Construisez des requêtes de manière interactive. Exécutez directement. Enregistrez les fichiers générés depuis le terminal.

Démarrage rapide

Installation

Hulak est distribué via xaaha/tap. Homebrew 6.0+ exige une confiance explicite pour les taps tiers ; sans elle, brew upgrade ignore silencieusement hulak. Opération à effectuer une seule fois par machine :

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

Autres options d'installation :

• go install github.com/xaaha/hulak@latest
• Compilez depuis les sources avec go build -o hulak

Completion du shell (go install / compilation depuis les sources)

Homebrew installe la completion automatiquement. Si vous avez installé via go install ou compilé depuis les sources, activez-la une seule fois :

# 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 nécessite autoload -Uz compinit && compinit dans votre .zshrc.

Option A. Client API avec secrets chiffrés (par défaut)

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 :

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

[!Note] Pour les 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 :

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 :

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

Exécutez la requête :

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

Vous préférez des fichiers env/*.env en clair aux secrets chiffrés ?

hulak init classic

Le mode texte en clair est entièrement pris en charge. Voir docs/environment.md pour plus d'informations

Coffre de secrets chiffrés ou fichiers .env en clair

Hulak fonctionne selon deux modes. Faites votre choix lors de hulak init. Vous pourrez migrer plus tard.

• Coffre (par défaut) : les secrets se trouvent dans .hulak/store.age, chiffrés avec une paire de clés age ou SSH. Peut être commité sans risque. Les équipes partagent via un fichier de destinataires. Voir docs/store.md.
• Texte en clair : les secrets se trouvent dans des fichiers env/*.env en clair. Plus simple, pas de chiffrement. Ajoutez env/ à .gitignore. Voir docs/environment.md.

Vous utilisez le mode classique et souhaitez changer ? Voir docs/migrating-to-vault.md.

Utilisation depuis un agent IA (MCP)

Hulak embarque un serveur MCP intégré, afin que des agents comme Claude Code, Cursor et Zed puissent piloter votre collection d'API en langage naturel — « lister les requêtes », « lancer un dry-run de login sur staging », « appeler getUser et afficher la réponse ».

Pour Claude Code, ajoutez-le avec une seule commande :

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

Cursor, Zed, Codex, opencode et Pi utilisent quant à eux un petit fichier de configuration. Voir docs/mcp.md pour chacun.

Les secrets ne quittent jamais votre machine : l'agent travaille avec les noms des requêtes et des environnements, jamais avec les valeurs déchiffrées. Les lectures et les 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.

Commandes

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 entrée que lorsque des fichiers référencent {{.key}}.
• Les sous-commandes hulak secrets demandent une entrée à chaque fois (sauf secrets list).
• Les shells non interactifs exigent --env <name>.

Pièges courants

• Ne commitez jamais ~/.config/hulak/identity.txt. C'est votre clé privée. Mode 0600. Sauvegardez-la d'abord. Voir docs/store.md#identity-backup.
• Lors de hulak init, -env crée des fichiers d'environnement. C'est une option 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 graphiques nécessitent une option d'attente pour secrets edit. Utilisez EDITOR="code -w" ou EDITOR="zed --wait". Sans cela, l'éditeur revient immédiatement et les modifications sont perdues.
• Les conflits de fusion sur nécessitent une procédure dédiée. Voir .

Structure du projet

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

Lancez l'explorateur avec un fichier ou un répertoire :

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

Lisez le guide complet dans docs/graphql-explorer.md.

Documentation

Commencez ici pour la référence complète :

• Coffre chiffré. Modèle de chiffrement, partage en équipe, CI.
• Migration vers le coffre. De env/ vers .hulak/.
• Versionner votre coffre. Workflow Git pour les secrets.
• Comparaison. Hulak vs SOPS, Bruno et autres.
• Corps de requête
• Actions
• Secrets d'environnement (mode classique)
• Fichiers de réponse
• Explorateur GraphQL
• Auth 2.0
• Serveur MCP. Exposez vos requêtes aux agents IA.

Pour l'interface de commande en direct, exécutez :

hulak help
hulak <command> --help

Prise en charge des schémas

Le schéma Hulak est disponible dans le Schema Store, de sorte que les éditeurs prenant en charge Schema Store peuvent activer automatiquement la complétion pour les fichiers .hk.yaml et .hk.yml.

Vous pouvez également pointer votre serveur de langage YAML directement vers :

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

Contribuer

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

Voir CONTRIBUTING.md pour le workflow 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.