hulak

Cliente de API nativo de Git con secretos cifrados.

_{REST · GraphQL · OAuth}

Inicio rápido • Explorador de GraphQL • Estructura del proyecto • Documentación

Ejecuta una petición, un directorio completo o permanece en modo interactivo

hulak run ./requests/

Hulak ejecuta archivos de petición directamente desde tu proyecto. Admite ejecución concurrente por directorio. Si simplemente ejecutas hulak, utiliza un selector interactivo como alternativa.

Explorador de GraphQL dedicado

Examina esquemas de múltiples endpoints. Busca operaciones. Construye consultas de forma interactiva. Ejecuta en línea. Guarda archivos generados desde la terminal.

Inicio rápido

Instalación

Hulak se distribuye mediante xaaha/tap. Homebrew 6.0+ exige confianza explícita para taps de terceros; sin ella, brew upgrade omite hulak silenciosamente. Es un paso único por máquina:

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

Otras opciones de instalación:

• go install github.com/xaaha/hulak@latest
• Compila desde el código fuente con go build -o hulak

Completado de shell (instalación con go install / compilación desde el código fuente)

Homebrew instala el completado automáticamente. Si instalaste mediante go install o compilaste desde el código fuente, actívalo una vez:

# 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)

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

Genera una petición de inicio; para ver rápidamente cómo es un archivo de petición, ejecuta:

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:

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:

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

Ejecuta la petición:

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

¿Prefieres archivos env/*.env en texto plano en lugar de secretos cifrados?

hulak init classic

El modo de texto plano es totalmente compatible. Consulta docs/environment.md para más información.

Almacén de secretos cifrado o archivos .env en texto plano

Hulak funciona en dos modos. Elige uno durante hulak init. Podrás migrar más adelante.

• Vault (predeterminado): los secretos residen en .hulak/store.age, cifrados con un par de claves age o SSH. Es seguro confirmarlos. Los equipos los comparten mediante un archivo de destinatarios. Consulta docs/store.md.
• Texto plano: los secretos residen en archivos env/*.env en texto plano. Más simple, sin cifrado. Añade env/ a .gitignore. Consulta docs/environment.md.

¿Estás usando el modo clásico y quieres cambiar? Consulta docs/migrating-to-vault.md.

Úsalo desde un agente de IA (MCP)

Hulak incluye un servidor MCP integrado, de modo que agentes como Claude Code, Cursor y Zed pueden manejar tu colección de API en lenguaje natural — "lista las peticiones", "prueba login contra staging", "llama a getUser y muestra la respuesta".

Para Claude Code, añádelo con un solo comando:

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

Cursor, Zed, Codex, opencode y Pi usan en su lugar un pequeño archivo de configuración. Consulta 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 pruebas en seco son de solo lectura; las escrituras se validan contra el esquema; los archivos de respuesta no se guardan a menos que se pida.

Configuración completa, referencia de herramientas y modelo de seguridad: docs/mcp.md.

Comandos

Ejecuta hulak <command> --help para ver las opciones y ejemplos por comando.

Comportamiento del selector

Si omites --env, se 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).
• Las shells no interactivas requieren --env <name>.

Errores comunes

• Nunca confirmes ~/.config/hulak/identity.txt. Es tu clave privada. Modo 0600. Haz una copia de seguridad primero. Consulta 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 GUI necesitan una opción de espera para secrets edit. Usa EDITOR="code -w" o EDITOR="zed --wait". Sin ella, el editor vuelve de inmediato y los cambios se pierden.
• Los conflictos de fusión en necesitan un procedimiento. Consulta .

Estructura del proyecto

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 de GraphQL

Inicia el explorador con un archivo o un directorio:

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.

Documentación

Empieza aquí para obtener la referencia completa:

• Almacén cifrado. Modelo de cifrado, uso compartido en equipo, CI.
• Migración al Vault. De env/ a .hulak/.
• Versionado de tu Vault. Flujo de trabajo Git para secretos.
• Comparativa. Hulak vs SOPS, Bruno y similares.
• Cuerpo de la petición
• Acciones
• Secretos de entorno (modo clásico)
• Archivos de respuesta
• Explorador de GraphQL
• Auth 2.0
• Servidor MCP. Expón tus peticiones a agentes de IA.

Para ver la superficie de comandos en vivo, ejecuta:

hulak help
hulak <command> --help

Soporte de esquema

El esquema de Hulak está disponible en el Schema Store, por lo que los editores compatibles con Schema Store pueden habilitar automáticamente el completado para archivos .hk.yaml y .hk.yml.

También puedes apuntar tu servidor de lenguaje YAML directamente a:

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

Contribuciones

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

Consulta CONTRIBUTING.md para conocer 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.