Для разработчиков

Флаги и скрипты

Сделать с агентом
Агент напишет скрипт на Pachca CLI под вашу задачу, покажет прогон без изменений и запустит его после вашего «да»
Напиши скрипт на 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 через браузер, дай мне готовыми командами.
Вставьте промпт в чат с ИИ-агентом, у которого есть терминал на вашей машине. Правила задачи знает скилл pachca-api.

Глобальные флаги

Доступны для всех команд. Таблица генерируется из исходного определения флагов в 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:

# Сообщения по возрастанию IDpachca messages list --chat-id 123 --sort id --order asc # Чаты по дате последнего сообщенияpachca chats list --sort last_message_at --order desc

Доступные поля сортировки зависят от команды, их список показывает --help. Поле указывают как в API, через подчёркивание, подробнее в разделе Имена флагов. Если --order не указан, chats list и messages list сортируют по убыванию (desc), а у команд поиска направление зависит от --sort: например, search list-users --sort alphabetical идёт по алфавиту (asc).

Имена флагов

Имена флагов CLI пишутся в kebab-case, через дефис, по стандартной конвенции для CLI-инструментов. В API-документации те же поля названы в snake_case:

API-документация          CLI-флаг─────────────────         ────────────────first_name            →   --first-namephone_number          →   --phone-numberentity_id             →   --entity-idskip_email_notify     →   --skip-email-notifylist_tags             →   --list-tagscustom_properties     →   --custom-propertiesparent_message_id     →   --parent-message-id

При отправке запроса CLI автоматически конвертирует имена обратно в snake_case для API. Значения флагов CLI не переписывает, поэтому варианты из перечня пишутся как в API: --sort last_message_at. Проверить тело запроса можно через --dry-run:

pachca users update 123 --first-name "Иван" --phone-number "+7900" --dry-run -o json | jq -c .body # {"user":{"first_name":"Иван","phone_number":"+7900"}}

Boolean-флаги

Для boolean-параметров API используйте флаг для установки true и --no- префикс для false:

# Деактивировать сотрудника (suspended: true)pachca users update 123 --suspended # Активировать обратно (suspended: false)pachca users update 123 --no-suspended # Создать публичный канал (channel: true, public: true)pachca chats create --name "Новости" --channel --public # Сделать канал приватным (public: false)pachca chats update 123 --no-public

Значение null

Если поле API принимает null, передайте во флаге слово null: CLI отправит в теле запроса JSON null. Так удаляют входящий вебхук бота и снимают ответ с черновика:

# Удалить входящий вебхук бота (webhook.kind: null)pachca bots update 456 --kind null # Снять ответ с черновика (draft.parent_message_id: null)pachca drafts update 789 --parent-message-id null

Что null значит для конкретного поля, сказано в справке флага: pachca bots update --help.

Предпросмотр запроса

Флаг --dry-run показывает HTTP-запрос без отправки — для отладки и проверки параметров:

pachca messages create --entity-id 123 --content "Привет" --dry-run #   POST https://api.pachca.com/api/shared/v1/messages#   Authorization: Bearer ••••••••#   Content-Type: application/json##   {#     "message": {#       "entity_id": 123,#       "content": "Привет"#     }#   }

В пайпе или с -o json тот же запрос приходит объектом с полями dry_run, method, url, headers и body, его удобно разбирать через jq. Предпросмотру токен не нужен: --dry-run работает и до pachca auth login, а токен в заголовке Authorization заменён маской.

Деструктивные операции

DELETE-команды требуют подтверждения в терминале. Флаг --force пропускает его:

# С подтверждением (TTY)pachca users delete 1234 # Без подтвержденияpachca users delete 1234 --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. Подробнее о двух структурах ответа — в разделе Ошибки.

Использование exit codes
pachca users get 123 || case $? in    3) echo "Нет доступа" ;;    4) echo "Пользователь не найден" ;;  esac

Ошибки

При -o json (или в пайпе) ошибки выводятся в stderr как JSON. Формат один для ошибок API, сети, авторизации, проверки флагов самим CLI и неизвестной команды. Набор полей зависит от источника ошибки:

API-ошибка (422)
{  "error": "content: не может быть пустым",  "code": 422,  "type": "PACHCA_VALIDATION_ERROR",  "request_id": "abc123",  "field": "content"}
Множественная валидация (422)
{  "error": "Validation failed",  "code": 422,  "type": "PACHCA_VALIDATION_ERROR",  "request_id": "abc123",  "errors": [    { "field": "content", "message": "не может быть пустым" },    { "field": "entity_id", "message": "обязательное поле" }  ]}
Проверка флагов самим CLI
{  "error": "Обязательный флаг --entity-id не передан",  "code": null,  "type": "PACHCA_VALIDATION_ERROR",  "flag": "--entity-id",  "hint": "Обязательные: --entity-id <integer>. pachca introspect messages create"}
Ошибка авторизации
{  "error": "Token not found",  "code": null,  "type": "PACHCA_AUTH_ERROR",  "hint": "pachca auth login, or set PACHCA_TOKEN"}
ПолеТипОписание
errorstringСообщение об ошибке
codenumber | nullHTTP-код ответа, null для ошибок до запроса или без ответа API
typestringТип ошибки (см. таблицу ниже)
messagestring?Подробность к error: код ошибки API (insufficient_scope, role_forbidden, invalid_token), текст сетевой ошибки или таймаута, причина неудачного входа
request_idstring?ID запроса к API (для обращения в поддержку)
hintstring?Подсказка, как исправить ошибку
fieldstring?Поле запроса, на которое указал API
validation_codestring?Код ошибки валидации от API, когда ошибка одна
flagstring?Флаг, который не прошёл проверку самого CLI, например --entity-id
scopestring?Право, которого не хватило токену, при PACHCA_SCOPE_ERROR
errorsarray?Список ошибок, когда их несколько: от API с полями field, message, code, value, от проверки CLI с полями message и flag
suggestionsarray?Похожие команды при 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 не получится.

Обработка ошибок в скрипте
# Получить ошибку как JSONERROR=$(pachca users get 999 -o json 2>&1 >/dev/null)TYPE=$(echo "$ERROR" | jq -r '.type') case "$TYPE" in  PACHCA_AUTH_ERROR) echo "Нет доступа" ;;  PACHCA_VALIDATION_ERROR) echo "Неверные данные" ;;  *) echo "Ошибка: $ERROR" ;;esac

Переменные окружения

ПеременнаяОписание
PACHCA_TOKENBearer-токен, удобно для 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_STOREfile — хранить токен в файле конфига вместо хранилища ключей ОС
PACHCA_TIMEOUTТаймаут запроса в секундах, если не заданы --timeout и настройка defaults.timeout (по умолчанию 30)
PACHCA_SIGNING_SECRETSigning 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.

PACHCA_TOKEN=YOUR_ACCESS_TOKEN pachca messages create --entity-id 123 --content "Деплой завершён" --no-input