hulak v0.3.32

Git-нативный API-клиент с шифрованными секретами.

_{REST · GraphQL · OAuth}

Быстрый старт • GraphQL Explorer • Структура проекта • Документация

Выполните один запрос, целую директорию или работайте в интерактивном режиме

hulak run ./requests/

Hulak выполняет файлы запросов прямо из вашего проекта. Он поддерживает параллельное выполнение директорий. Если вы просто запустите hulak, он переключится на интерактивный выбор.

Выделенный GraphQL Explorer

Просматривайте схемы с нескольких эндпоинтов. Ищите операции. Стройте запросы в интерактивном режиме. Выполняйте их прямо в интерфейсе. Сохраняйте сгенерированные файлы из терминала.

Быстрый старт

Установка

Hulak распространяется через xaaha/tap. Начиная с Homebrew 6.0+ требуется явное доверие сторонним tap-репозиториям; без этого brew upgrade молча пропускает hulak. Достаточно выполнить один раз на машине:

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

Другие способы установки:

• go install github.com/xaaha/hulak@latest
• Сборка из исходников командой go build -o hulak

Автодополнение в shell (go install / сборка из исходников)

Homebrew устанавливает автодополнение автоматически. Если вы установили через go install или собрали из исходников, включите его один раз:

# 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 требуется autoload -Uz compinit && compinit в вашем .zshrc.

Вариант A. API-клиент с шифрованными секретами (по умолчанию)

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

Создайте стартовый запрос, чтобы быстро посмотреть, как выглядит файл запроса, выполните:

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

[!Note] Для других типов выполните: hulak example. Подкоманда example — это быстрый способ создать файл запроса, который можно изменить. Подробнее: hulak example -h

Чтобы настроить секрет, выполните:

hulak secrets keys set placeholder  https://jsonplaceholder.typicode.com/posts -env prod

Теперь в файле example-api.hk.yaml вы можете сослаться на этот секрет:

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

Выполните запрос:

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

Предпочитаете обычные текстовые файлы env/*.env вместо шифрованных секретов?

hulak init classic

Режим plaintext полностью поддерживается. Дополнительная информация — в docs/environment.md.

Хранилище шифрованных секретов или обычные файлы .env

Hulak работает в двух режимах. Выберите один при hulak init. Позже можно перейти на другой.

• Vault (по умолчанию): секреты хранятся в .hulak/store.age, зашифрованные с помощью age или SSH-ключевой пары. Можно безопасно коммитить. Для команд — общий файл получателей. См. docs/store.md.
• Plaintext: секреты хранятся в открытом виде в файлах env/*.env. Проще, без шифрования. Добавьте env/ в .gitignore. См. docs/environment.md.

Используете классический режим и хотите переключиться? См. docs/migrating-to-vault.md.

Использование через ИИ-агента (MCP)

Hulak включает встроенный MCP сервер, поэтому такие агенты, как Claude Code, Cursor и Zed, могут управлять вашей коллекцией API на простом языке — «перечисли запросы», «сделай dry-run login на staging», «вызови getUser и покажи ответ».

Для Claude Code добавьте его одной командой:

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

Cursor, Zed, Codex, opencode и Pi вместо этого используют небольшой конфигурационный файл. Инструкции для каждого — в docs/mcp.md.

Секреты никогда не покидают вашу машину: агент работает с именами запросов и окружений, но никогда с расшифрованными значениями. Чтение и dry-run выполняются только для чтения; записи проверяются по схеме; файлы ответов не сохраняются, если об этом не попросить.

Полная настройка, справочник инструментов и модель безопасности: docs/mcp.md.

Команды

Выполните hulak <command> --help, чтобы увидеть флаги и примеры для каждой команды.

Поведение интерактивного выбора

Если опустить --env, откроется интерактивный выбор.

• hulak run и hulak gql запрашивают выбор, только если файлы ссылаются на {{.key}}.
• Подкоманды hulak secrets запрашивают выбор каждый раз (кроме secrets list).
• В неинтерактивных оболочках требуется --env <name>.

Распространённые ошибки

• Никогда не коммитьте ~/.config/hulak/identity.txt. Это ваш закрытый ключ. Права 0600. Сначала сделайте резервную копию. См. docs/store.md#identity-backup.
• При hulak init флаг -env создаёт env-файлы. Это флаг настройки, а не выбора в рантайме. hulak init -env staging prod создаст два окружения.
• env — псевдоним для secrets. hulak env list работает так же, как hulak secrets list.
• Графическим редакторам нужен флаг ожидания для secrets edit. Используйте EDITOR="code -w" или EDITOR="zed --wait". Без него редактор завершается сразу и изменения теряются.
• Для merge-конфликтов в store.age есть готовая инструкция. См. docs/versioning.md#merge-conflicts.

Структура проекта

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

Запустите обозреватель с файлом или директорией:

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

Полное руководство — в docs/graphql-explorer.md.

Документация

Полный справочник начинается здесь:

• Шифрованное хранилище. Модель шифрования, работа в команде, CI.
• Переход на хранилище. С env/ на .hulak/.
• Версионирование хранилища. Git-процесс для секретов.
• Сравнение. Hulak против SOPS, Bruno и других.
• Тело запроса
• Действия
• Секреты окружения (классический режим)
• Файлы ответов
• GraphQL Explorer
• Auth 2.0
• MCP-сервер. Откройте доступ к вашим запросам для ИИ-агентов.

Чтобы увидеть полный список команд, выполните:

hulak help
hulak <command> --help

Поддержка схем

Схема Hulak доступна в Schema Store, поэтому редакторы, поддерживающие Schema Store, могут автоматически включить автодополнение для файлов .hk.yaml и .hk.yml.

Вы также можете указать вашему YAML language server напрямую на:

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

Участие в разработке

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

Полный процесс разработки описан в CONTRIBUTING.md.

Поддержка проекта

Если Hulak вам полезен, откройте issue, предложите функцию, отправьте pull request или поддержите проект финансово.