Флаги и скрипты
Напиши скрипт на Pachca CLI под мою задачу. Скачай страницу документации и делай по ней: `curl -sL https://dev.pachca.com/guides/cli/scripting.md`. Инструмент для веба отдаёт пересказ, бери его, только если curl не сработал. Если страница не открылась и так, остановись и скажи. Если у тебя есть скилл `pachca-api`, работай и по нему. 1. Спроси, что должен делать скрипт и где его запускать: здесь или в CI. 2. Запусти `pachca doctor`. Если он не проходит, настрой CLI по странице установки: `curl -sL https://dev.pachca.com/guides/cli/installation.md`. Для CI токен я положу в секрет CI `PACHCA_TOKEN`, а для прогона здесь в `.env`, добавь `.env` в `.gitignore`. CLI сам `.env` не читает: скрипт загружает его в начале, если файл есть. 3. Напиши скрипт в этой папке по разделам «Неинтерактивный режим», «Exit codes» и «Ошибки». Флаги сверяй по `--help`, вывод бери с `-o json`, списки целиком с `--all`. 4. Без флага `--apply` скрипт выполняет меняющие команды с `--dry-run` из раздела «Предпросмотр запроса», а читающие как есть. Флаг `--force` ставь только на удаление, о котором я просил. 5. Запусти скрипт без `--apply` и покажи, что и где он изменит. После моего «да» запусти с `--apply` и проверь результат. Упавшую команду, которая создаёт или отправляет, повторяй, только убедившись, что она не прошла. 6. Перечисли, что создано и изменено, дай команды запуска и скажи, как отменить сделанное. Если мешают права, роль или настройки пространства, не обходи: скажи, что мешает и кто это изменит. Чего не можешь сам, например войти в CLI через браузер, дай мне готовыми командами.
Глобальные флаги
Доступны для всех команд. Таблица генерируется из исходного определения флагов в CLI — всегда актуальна:
| Флаг | Короткий | Описание |
|---|---|---|
--output <value> | -o | Формат вывода: table, json, yaml, csv |
--columns <value> | -c | Колонки для вывода table, csv и --plain (через запятую) |
--no-header | Скрыть строку заголовков в table и csv | |
--no-truncate | Не обрезать длинные значения | |
--profile <value> | -p | Профиль для этой команды |
--token <value> | Токен для этого вызова (без сохранения) | |
--quiet | -q | Подавить вывод (только exit code и ошибки) |
--no-color | Отключить цвета | |
--verbose | -v | Показывать HTTP-запросы и ответы |
--no-input | Отключить интерактивные промпты | |
--dry-run | Показать запрос без отправки | |
--timeout <value> | Таймаут запроса в секундах (по умолчанию 30) | |
--no-retry | Отключить автоповтор при 429, 5xx и сетевых ошибках | |
--plain | Плоский вывод: TSV без заголовка, ID первым, без цвета (для скриптов) |
Флаг --force (пропуск подтверждения DELETE) задаётся не глобально, а у деструктивных команд — см. Деструктивные операции.
CLI сам повторяет запросы после 429 и временных ошибок сервера по правилам из раздела Повторные запросы. Ответ 429 со сроком дольше минуты CLI не повторяет и сразу завершает команду с кодом 1. Срока паузы в ошибке нет, поэтому остановите скрипт и вернитесь к задаче позже без пробных запросов. Сетевую ошибку он повторяет так же, как 5xx: только у запросов GET, PUT и DELETE. Таймаут не повторяется ни у какого метода. Если команда, которая создаёт или отправляет, завершилась сетевой ошибкой, таймаутом или 5xx, запрос мог пройти: прежде чем повторить её в скрипте, проверьте чтением, что результата нет.
Сортировка
Команды списков поддерживают сортировку через --sort и --order:
Доступные поля сортировки зависят от команды, их список показывает --help. Поле указывают как в API, через подчёркивание, подробнее в разделе Имена флагов. Если --order не указан, chats list и messages list сортируют по убыванию (desc), а у команд поиска направление зависит от --sort: например, search list-users --sort alphabetical идёт по алфавиту (asc).
Имена флагов
Имена флагов CLI пишутся в kebab-case, через дефис, по стандартной конвенции для CLI-инструментов. В API-документации те же поля названы в snake_case:
При отправке запроса CLI автоматически конвертирует имена обратно в snake_case для API. Значения флагов CLI не переписывает, поэтому варианты из перечня пишутся как в API: --sort last_message_at. Проверить тело запроса можно через --dry-run:
Boolean-флаги
Для boolean-параметров API используйте флаг для установки true и --no- префикс для false:
Значение null
Если поле API принимает null, передайте во флаге слово null: CLI отправит в теле запроса JSON null. Так удаляют входящий вебхук бота и снимают ответ с черновика:
Что null значит для конкретного поля, сказано в справке флага: pachca bots update --help.
Предпросмотр запроса
Флаг --dry-run показывает HTTP-запрос без отправки — для отладки и проверки параметров:
В пайпе или с -o json тот же запрос приходит объектом с полями dry_run, method, url, headers и body, его удобно разбирать через jq. Предпросмотру токен не нужен: --dry-run работает и до pachca auth login, а токен в заголовке Authorization заменён маской.
Деструктивные операции
DELETE-команды требуют подтверждения в терминале. Флаг --force пропускает его:
Команда pachca api DELETE отправляет запрос сразу, без подтверждения и флага --force. Проверить его заранее можно флагом --dry-run.
Exit codes
| Код | Значение |
|---|---|
0 | Успех |
1 | Ошибка API, сети или таймаут: 400, 409, 429, 5xx и 403 с массивом errors |
2 | Неверные флаги или аргументы, неверный вызов команды (PACHCA_USAGE_ERROR), метод не найден в справочнике pachca api, удаление без --force в неинтерактивном режиме, ошибка валидации 422 от API |
3 | Ошибка аутентификации: токен не найден, вход завершён, не удался вход pachca auth login, 401 или 403 по праву токена или роли его владельца (insufficient_scope, role_forbidden) |
4 | Ресурс не найден (404) |
Код 403 бывает двух видов. Отказ из-за скоупа токена или роли его владельца даёт код 3, а отказ в доступе к самому объекту (чат закрыт, правило чата не разрешает действие) приходит с массивом errors и даёт код 1 с типом PACHCA_API_ERROR. Подробнее о двух структурах ответа — в разделе Ошибки.
Ошибки
При -o json (или в пайпе) ошибки выводятся в stderr как JSON. Формат один для ошибок API, сети, авторизации, проверки флагов самим CLI и неизвестной команды. Набор полей зависит от источника ошибки:
| Поле | Тип | Описание |
|---|---|---|
error | string | Сообщение об ошибке |
code | number | null | HTTP-код ответа, null для ошибок до запроса или без ответа API |
type | string | Тип ошибки (см. таблицу ниже) |
message | string? | Подробность к error: код ошибки API (insufficient_scope, role_forbidden, invalid_token), текст сетевой ошибки или таймаута, причина неудачного входа |
request_id | string? | ID запроса к API (для обращения в поддержку) |
hint | string? | Подсказка, как исправить ошибку |
field | string? | Поле запроса, на которое указал API |
validation_code | string? | Код ошибки валидации от API, когда ошибка одна |
flag | string? | Флаг, который не прошёл проверку самого CLI, например --entity-id |
scope | string? | Право, которого не хватило токену, при PACHCA_SCOPE_ERROR |
errors | array? | Список ошибок, когда их несколько: от API с полями field, message, code, value, от проверки CLI с полями message и flag |
suggestions | array? | Похожие команды при PACHCA_COMMAND_NOT_FOUND |
| Тип | Описание |
|---|---|
PACHCA_API_ERROR | Ошибка API: 400, 403 с массивом errors, 409, 429, 5xx и другие неожиданные ответы |
PACHCA_AUTH_ERROR | Ошибка аутентификации: токен не найден, вход через браузер завершён (Session expired), 401 или 403 с role_forbidden |
PACHCA_VALIDATION_ERROR | Ошибка валидации 422 от API или проверка флагов самим CLI до запроса: пропущен обязательный флаг без терминала, значение длиннее допустимого или неверный JSON во флаге. У проверки CLI code: null и поле flag. |
PACHCA_SCOPE_ERROR | Токену не хватает скоупа (403 с insufficient_scope) |
PACHCA_NETWORK_ERROR | Сеть недоступна |
PACHCA_TIMEOUT_ERROR | Таймаут запроса |
PACHCA_USAGE_ERROR | Команду вызвали неверно: взаимоисключающие флаги, нет полей для обновления, профиль или файл не найден, неверный JSON в --data или --input у pachca api |
PACHCA_DESTRUCTIVE_OP_ERROR | Удаление без --force в неинтерактивном режиме |
PACHCA_COMMAND_NOT_FOUND | Команда не найдена, похожие команды приходят в suggestions |
PACHCA_AUTH_LOGIN_ERROR | Не удался вход командой pachca auth login |
PACHCA_NOT_FOUND_ERROR | Справка pachca api с --describe, --spec или --docs не нашла такой метод |
Ошибки разбора флагов и аргументов (неизвестный флаг, значение не того типа или не из списка --help, пропущенный аргумент) CLI выводит обычным текстом даже при -o json. Код выхода у них тоже 2, но разобрать stderr через jq не получится.
Переменные окружения
| Переменная | Описание |
|---|---|
PACHCA_TOKEN | Bearer-токен, удобно для CI. Уступает только флагам --token и --profile, порядок — в разделе Приоритет токена. |
PACHCA_PROFILE | Профиль для команды, когда не заданы --profile и PACHCA_TOKEN |
PACHCA_HOME | Родительский каталог конфига: CLI хранит файлы в $PACHCA_HOME/pachca. Удобно для изоляции в CI, тестах и у агентов. Порядок выбора каталога — в разделе Настройки. |
PACHCA_API_URL | Другой адрес сервера API — все команды пойдут туда. По умолчанию https://api.pachca.com/api/shared/v1. |
PACHCA_SECRET_STORE | file — хранить токен в файле конфига вместо хранилища ключей ОС |
PACHCA_TIMEOUT | Таймаут запроса в секундах, если не заданы --timeout и настройка defaults.timeout (по умолчанию 30) |
PACHCA_SIGNING_SECRET | Signing secret бота: им pachca bots listen-events --forward-to подписывает события для обработчика. Подробнее — в разделе Через CLI. |
PACHCA_PROMPT_DISABLED | Отключить интерактивные промпты (для агентов) |
CI | Автоматический неинтерактивный режим |
NO_COLOR | Отключить цвет |
FORCE_COLOR | Принудительно включить цвет |
PACHCA_SKIP_NEW_VERSION_CHECK | Отключить проверку обновлений |
Неинтерактивный режим
CLI автоматически переходит в неинтерактивный режим при любом из условий: stdin или stdout — не TTY, установлена PACHCA_PROMPT_DISABLED или CI. В этом режиме нет промптов и спиннера, а при пропущенных обязательных флагах вместо вопроса приходит ошибка.
Флаг --no-input отключает только промпты: пропущенный обязательный флаг тоже даёт ошибку, а удаление без --force не выполняется. Спиннер в терминале при этом остаётся. Чтобы убрать и его, задайте PACHCA_PROMPT_DISABLED.