xaaha/hulakUn cliente CLI de API ligero basado en archivos con secretos cifrados con age, soporte GraphQL de primera clase y un servidor MCP integrado para flujos de trabajo de agentes de 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">
Tu mensajero en la terminal.
</h3>
<p align="center">
<a href="#quick-start">Inicio rápido</a> •
<a href="#graphql-explorer">Explorador GraphQL</a> •
<a href="#project-layout">Estructura del proyecto</a> •
<a href="#documentation">Documentación</a>
</p>
---
### Ejecuta una petición, un directorio completo o mantente en modo interactivo
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
Hulak ejecuta archivos de peticiones directamente desde tu proyecto. Admite la ejecución concurrente de directorios. Recurre a un selector interactivo cuando simplemente ejecutas `hulak`.
### Explorador GraphQL dedicado
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
Explora esquemas desde múltiples endpoints. Busca operaciones. Construye consultas de forma interactiva. Ejecuta en línea. Guarda los archivos generados desde la terminal.
## Inicio rápido
### Instalación
Hulak se distribuye a través de [xaaha/tap](https://github.com/xaaha/homebrew-tap). Homebrew 6.0+ requiere confianza explícita para taps de terceros; sin ella, `brew upgrade` omite hulak silenciosamente. Paso único por máquina:
```bash
brew trust xaaha/tap
brew install --cask xaaha/tap/hulak
```
Otras opciones de instalación:
- `go install github.com/xaaha/hulak@latest`
- Compilar desde el código fuente con `go build -o hulak`
#### Autocompletado de shell (go install / compilaciones desde el código fuente)
Homebrew instala el autocompletado automáticamente. Si instalaste mediante `go install`
o compilaste desde el código fuente, actívalo una vez:
```bash
# 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 requiere `autoload -Uz compinit && compinit` en tu `.zshrc`.
### Ruta A. Cliente de API con secretos cifrados (predeterminado)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
Genera una petición inicial; para comprobar rápidamente cómo es un archivo de petición, ejecuta:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> Para otros tipos, ejecuta: `hulak example`. El subcomando `example` te ofrece una forma rápida de escribir un archivo de petición que puedes modificar. Para más información, ejecuta `hulak example -h`
Para configurar un secreto puedes ejecutar:
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
Ahora, en tu archivo `example-api.hk.yaml`, puedes hacer referencia a este secreto:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Ejecuta la petición:
```bash
hulak run example-api.hk.yaml --env prod
```
### ¿Prefieres archivos `env/*.env` en texto plano en lugar de secretos cifrados?
```bash
hulak init classic
```
El modo de texto plano es totalmente compatible. Consulta [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md) para más información
## Bóveda de secretos cifrados o archivos `.env` en texto plano
Hulak funciona en dos modos. Elige uno durante `hulak init`. Puedes migrar más adelante.
- **Bóveda (predeterminado):** los secretos residen en `.hulak/store.age`, cifrados con un par de claves age o SSH. Seguro para hacer commit. Los equipos comparten mediante un archivo de destinatarios. Consulta [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **Texto plano:** los secretos residen en archivos `env/*.env` en texto plano. Más sencillo, sin cifrado. Añade `env/` a `.gitignore`. Consulta [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
¿Usas el modo clásico y quieres cambiar? Consulta [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## Úsalo desde un agente de IA (MCP)
Hulak incluye un servidor [MCP](https://modelcontextprotocol.io) integrado, para que agentes como Claude Code, Cursor y Zed puedan manejar tu colección de API en lenguaje natural — "lista las peticiones", "ejecuta en seco `login` contra staging", "llama a `getUser` y muestra la respuesta".
Para Claude Code, añádelo con un solo comando:
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
Cursor, Zed, Codex, opencode y Pi usan un pequeño archivo de configuración en su lugar. Consulta [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) para cada uno.
Los secretos nunca salen de tu máquina: el agente trabaja con **nombres** de peticiones y entornos, nunca con valores descifrados. Las lecturas y ejecuciones en seco son de solo lectura; las escrituras se validan contra el esquema; los archivos de respuesta no se guardan a menos que se soliciten.
Configuración completa, referencia de herramientas y modelo de seguridad: [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## Comandos
| Comando | Propósito | Leer más |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | Ejecutar archivo(s) de petición o un directorio | [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 del explorador GraphQL | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | CRUD de la bóveda cifrada | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | Inicializar un proyecto hulak | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Conversión de Postman a hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | Generar archivos de petición de ejemplo | — |
| `doctor` | Comprobar la salud del proyecto | — |
| `mcp` | Servir peticiones a agentes de IA mediante MCP | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | Mostrar la versión | — |
Ejecuta `hulak <command> --help` para ver las opciones y ejemplos de cada comando.
### Comportamiento del selector
Omitir `--env` abre un selector interactivo.
- `hulak run` y `hulak gql` solo preguntan cuando los archivos hacen referencia a `{{.key}}`.
- Los subcomandos de `hulak secrets` preguntan siempre (excepto `secrets list`).
- Los shells no interactivos requieren `--env <name>`.
## Errores comunes
- **Nunca hagas commit de `~/.config/hulak/identity.txt`.** Esa es tu clave privada. Modo 0600. Haz una copia de seguridad primero. Consulta [docs/store.md#identity-backup](https://github.com/xaaha/hulak/blob/main/docs/store.md#identity-backup).
- **En `hulak init`, `-env` crea archivos de entorno. Es una opción de configuración, no un selector en tiempo de ejecución.** `hulak init -env staging prod` genera dos entornos.
- **`env` es un alias de `secrets`.** `hulak env list` funciona igual que `hulak secrets list`.
- **Los editores con GUI necesitan una opción de espera para `secrets edit`.** Usa `EDITOR="code -w"` o `EDITOR="zed --wait"`. Sin ella, el editor regresa inmediatamente y los cambios se pierden.
- **Los conflictos de fusión en `store.age` necesitan una receta.** Consulta [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## Estructura del proyecto
```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.
```
## Explorador GraphQL
Inicia el explorador con un archivo o un directorio:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
Lee la guía completa en [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## Documentación
Empieza aquí para la referencia completa:
- [Almacén cifrado](https://github.com/xaaha/hulak/blob/main/docs/store.md). Modelo de cifrado, uso compartido en equipo, CI.
- [Migrar a la bóveda](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). De `env/` a `.hulak/`.
- [Versionar tu bóveda](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). Flujo de trabajo con Git para secretos.
- [Comparación](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak vs SOPS, Bruno y similares.
- [Cuerpo de la petición](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Acciones](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Secretos de entorno (modo clásico)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Archivos de respuesta](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [Explorador 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)
- [Servidor MCP](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). Expón tus peticiones a agentes de IA.
Para la superficie de comandos en vivo, ejecuta:
```bash
hulak help
hulak <command> --help
```
## Compatibilidad de esquemas
El esquema de Hulak está disponible en el [Schema Store](https://www.schemastore.org/), por lo que los editores compatibles con Schema Store pueden habilitar automáticamente el autocompletado para archivos `.hk.yaml` y `.hk.yml`.
También puedes apuntar tu servidor de lenguaje YAML directamente a:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## Contribuir
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
Consulta [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md) para el flujo de trabajo de desarrollo completo.
## Apoya el proyecto
Si Hulak te resulta útil, abre un issue, sugiere una funcionalidad, envía un pull request o patrocina el proyecto.