xaaha/hulakЛегкий файловый CLI-клиент API с age-шифрованием секретов, полноценной поддержкой GraphQL и встроенным MCP-сервером для рабочих процессов ИИ-агентов.
<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">
Ваш мессенджер в терминале.
</h3>
<p align="center">
<a href="#quick-start">Быстрый старт</a> •
<a href="#graphql-explorer">GraphQL Explorer</a> •
<a href="#project-layout">Структура проекта</a> •
<a href="#documentation">Документация</a>
</p>
---
### Запустите один запрос, целый каталог или оставайтесь в интерактивном режиме
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
Hulak запускает файлы запросов напрямую из вашего проекта. Он поддерживает параллельное выполнение по каталогу. Если вы просто запустите `hulak`, откроется интерактивный выбор.
### Отдельный GraphQL Explorer
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
Просматривайте схемы с нескольких эндпоинтов. Ищите операции. Создавайте запросы интерактивно. Выполняйте их прямо на месте. Сохраняйте сгенерированные файлы из терминала.
## Быстрый старт
### Установка
Hulak распространяется через [xaaha/tap](https://github.com/xaaha/homebrew-tap). Homebrew 6.0+ требует явного доверия для сторонних tap-репозиториев; без него `brew upgrade` молча пропускает hulak. Это разовый шаг для каждой машины:
```bash
brew trust xaaha/tap
brew install --cask xaaha/tap/hulak
```
Другие варианты установки:
- `go install github.com/xaaha/hulak@latest`
- Сборка из исходников с помощью `go build -o hulak`
#### Автодополнение оболочки (go install / сборка из исходников)
Homebrew устанавливает автодополнение автоматически. Если вы установили через `go install`
или собрали из исходников, включите его один раз:
```bash
# zsh
hulak completion zsh > "${fpath[1]}/_hulak" # затем перезапустите оболочку
# 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-клиент с зашифрованными секретами (по умолчанию)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
Создайте стартовый запрос; чтобы быстро посмотреть, как выглядит файл запроса, выполните:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> Для других типов выполните: `hulak example`. Подкоманда `example` даёт быстрый способ создать файл запроса, который вы можете изменить. Для получения дополнительной информации выполните `hulak example -h`
Чтобы настроить секрет, выполните:
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
Теперь в вашем файле `example-api.hk.yaml` вы можете ссылаться на этот секрет:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
Запустите запрос:
```bash
hulak run example-api.hk.yaml --env prod
```
### Предпочитаете обычные текстовые файлы `env/*.env` вместо зашифрованных секретов?
```bash
hulak init classic
```
Режим с открытым текстом полностью поддерживается. Подробнее см. [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
## Хранилище зашифрованных секретов или текстовые файлы `.env`
Hulak работает в двух режимах. Выберите один при `hulak init`. Позже можно мигрировать.
- **Хранилище (по умолчанию):** секреты хранятся в `.hulak/store.age`, зашифрованные с помощью age или пары ключей SSH. Безопасно коммитить. Команды делятся ими через файл получателей. См. [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **Открытый текст:** секреты хранятся в текстовых файлах `env/*.env`. Проще, без шифрования. Добавьте `env/` в `.gitignore`. См. [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
Работаете в classic-режиме и хотите переключиться? См. [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## Использование из AI-агента (MCP)
Hulak включает встроенный сервер [MCP](https://modelcontextprotocol.io), поэтому такие агенты, как Claude Code, Cursor и Zed, могут управлять вашей коллекцией API на естественном языке — «покажи список запросов», «сделай dry-run `login` против staging», «вызови `getUser` и покажи ответ».
Для Claude Code добавьте его одной командой:
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
Cursor, Zed, Codex, opencode и Pi используют вместо этого небольшой файл конфигурации. См. [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) для каждого из них.
Секреты никогда не покидают вашу машину: агент работает с **именами** запросов и окружений, но никогда с расшифрованными значениями. Чтение и dry-run доступны только для чтения; запись проверяется по схеме; файлы ответов не сохраняются, если об этом не попросили.
Полная настройка, справочник по инструментам и модель безопасности: [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## Команды
| Команда | Назначение | Подробнее |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | Выполнить файл(ы) запросов или каталог | [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-проводник GraphQL | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | CRUD для зашифрованного хранилища | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | Инициализировать проект hulak | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | Конвертация Postman в hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | Создать образцы файлов запросов | — |
| `doctor` | Проверить состояние проекта | — |
| `mcp` | Обслуживать запросы для AI-агентов через MCP | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | Показать версию | — |
Выполните `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](https://github.com/xaaha/hulak/blob/main/docs/store.md#identity-backup).
- **При `hulak init` флаг `-env` создаёт файлы окружений. Это флаг настройки, а не селектор во время выполнения.** `hulak init -env staging prod` создаёт два окружения.
- **`env` — это псевдоним для `secrets`.** `hulak env list` работает так же, как `hulak secrets list`.
- **GUI-редакторам нужен флаг ожидания для `secrets edit`.** Используйте `EDITOR="code -w"` или `EDITOR="zed --wait"`. Без него редактор возвращает управление сразу, и изменения теряются.
- **Конфликты слияния в `store.age` требуют рецепта.** См. [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## Структура проекта
```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.
```
## GraphQL Explorer
Запустите проводник с файлом или каталогом:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
Полное руководство читайте в [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## Документация
Начните отсюда для полного справочника:
- [Зашифрованное хранилище](https://github.com/xaaha/hulak/blob/main/docs/store.md). Модель шифрования, общий доступ в команде, CI.
- [Миграция в хранилище](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). Из `env/` в `.hulak/`.
- [Версионирование вашего хранилища](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). Git-процесс для секретов.
- [Сравнение](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak против SOPS, Bruno и других.
- [Тело запроса](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [Действия](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [Секреты окружения (classic-режим)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [Файлы ответов](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [GraphQL Explorer](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)
- [Auth 2.0](https://github.com/xaaha/hulak/blob/main/docs/auth20.md)
- [MCP-сервер](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). Откройте ваши запросы для AI-агентов.
Чтобы увидеть актуальный набор команд, выполните:
```bash
hulak help
hulak <command> --help
```
## Поддержка схем
Схема Hulak доступна в [Schema Store](https://www.schemastore.org/), поэтому редакторы, поддерживающие Schema Store, могут автоматически включать автодополнение для файлов `.hk.yaml` и `.hk.yml`.
Вы также можете указать вашему языковому серверу YAML напрямую:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## Участие в разработке
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
Полный процесс разработки см. в [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md).
## Поддержка проекта
Если Hulak вам полезен, откройте issue, предложите функцию, отправьте pull request или спонсируйте проект.