Инструменты

CLI

Официальный CLI для работы с Pachca API из терминала. Каждый API-метод доступен как команда с типизированными флагами, валидацией и интерактивными подсказками. Требуется Node.js 20 или новее.

# Глобальная установкаnpm install -g @pachca/cli # Проверкаpachca --version # Или без установкиnpx @pachca/cli users list --token YOUR_ACCESS_TOKEN

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

Вход в аккаунт

Сохраните API-токен. Получить его можно в интерфейсе Пачки в разделе Автоматизации > API — подробнее в руководстве Авторизация.

# Интерактивный входpachca auth login # Для CI и скриптов — передайте токен через флагpachca auth login --token YOUR_ACCESS_TOKEN

Первая команда

Получите список сотрудников:

pachca users list # ID    Имя              Email               Роль# 1234  Иван Иванов      ivan@company.ru     admin# 5678  Мария Петрова    maria@company.ru    user

Добавьте -o json для JSON-вывода.

Отправка сообщения

Отправьте сообщение в канал или беседу:

pachca messages create --entity-id 123 --content "Привет!"

Если не указать обязательные флаги — CLI запросит их интерактивно.

Авторизация

Профили

CLI поддерживает несколько профилей — удобно, если вы работаете с персональным токеном и токенами ботов одновременно:

# Добавить профилиpachca auth login --profile personalpachca auth login --profile bot-notify # Для CI — передайте токен через флагpachca auth login --profile bot-notify --token YOUR_ACCESS_TOKEN # Список профилейpachca auth list # Переключить активный профильpachca auth switch bot-notify # Статус текущего профиляpachca auth status # Удалить профильpachca auth logout bot-notify

Токены хранятся в ~/.config/pachca/config.toml с правами chmod 600.

Приоритет токена

При выполнении команды CLI определяет токен в следующем порядке:

Флаг --token — разовое использование, без сохранения
Переменная PACHCA_TOKEN — удобно для CI
Флаг --profile или переменная PACHCA_PROFILE — конкретный профиль
Активный профиль — выбранный через pachca auth switch

# Токен через флаг (разово, без сохранения)pachca users list --token YOUR_ACCESS_TOKEN # Токен через переменную окружения (CI)PACHCA_TOKEN=YOUR_ACCESS_TOKEN pachca users list # Конкретный профиль для одной командыpachca messages create --profile bot-notify --entity-id 123 --content "Уведомление"

Команды

Паттерн всех команд: pachca [секция] [действие] [--флаги]

Имена команд совпадают с URL документации:

dev.pachca.com/api/messages/create  →  pachca messages createdev.pachca.com/api/chats/list       →  pachca chats listdev.pachca.com/api/members/add      →  pachca members add

Все команды

Команда	Метод API
`pachca common request-export`	POSTЭкспорт сообщений
`pachca common direct-url`	POSTЗагрузка файла
`pachca common uploads`	POSTПолучение подписи, ключа и других параметров
`pachca common get-exports`	GETСкачать архив экспорта
`pachca common custom-properties`	GETСписок дополнительных полей
`pachca profile get-info`	GETИнформация о токене
`pachca profile get`	GETИнформация о профиле
`pachca profile get-status`	GETТекущий статус
`pachca profile update-avatar`	PUTЗагрузка аватара
`pachca profile update-status`	PUTНовый статус
`pachca profile delete-avatar`	DELETEУдаление аватара
`pachca profile delete-status`	DELETEУдаление статуса
`pachca users create`	POSTСоздать сотрудника
`pachca users list`	GETСписок сотрудников
`pachca users get`	GETИнформация о сотруднике
`pachca users get-status`	GETСтатус сотрудника
`pachca users update`	PUTРедактирование сотрудника
`pachca users update-avatar`	PUTЗагрузка аватара сотрудника
`pachca users update-status`	PUTНовый статус сотрудника
`pachca users delete`	DELETEУдаление сотрудника
`pachca users remove-avatar`	DELETEУдаление аватара сотрудника
`pachca users remove-status`	DELETEУдаление статуса сотрудника
`pachca group-tags create`	POSTНовый тег
`pachca group-tags list`	GETСписок тегов сотрудников
`pachca group-tags get`	GETИнформация о теге
`pachca group-tags list-users`	GETСписок сотрудников тега
`pachca group-tags update`	PUTРедактирование тега
`pachca group-tags delete`	DELETEУдаление тега
`pachca chats create`	POSTНовый чат
`pachca chats list`	GETСписок чатов
`pachca chats get`	GETИнформация о чате
`pachca chats update`	PUTОбновление чата
`pachca chats archive`	PUTАрхивация чата
`pachca chats unarchive`	PUTРазархивация чата
`pachca members add-group-tags`	POSTДобавление тегов
`pachca members add`	POSTДобавление пользователей
`pachca members list`	GETСписок участников чата
`pachca members update`	PUTРедактирование роли
`pachca members remove-group-tag`	DELETEИсключение тега
`pachca members leave`	DELETEВыход из беседы или канала
`pachca members remove`	DELETEИсключение пользователя
`pachca threads add`	POSTНовый тред
`pachca threads get`	GETИнформация о треде
`pachca messages create`	POSTНовое сообщение
`pachca messages pin`	POSTЗакрепление сообщения
`pachca messages list`	GETСписок сообщений чата
`pachca messages get`	GETИнформация о сообщении
`pachca messages update`	PUTРедактирование сообщения
`pachca messages delete`	DELETEУдаление сообщения
`pachca messages unpin`	DELETEОткрепление сообщения
`pachca read-member list-readers`	GETСписок прочитавших сообщение
`pachca reactions add`	POSTДобавление реакции
`pachca reactions list`	GETСписок реакций
`pachca reactions remove`	DELETEУдаление реакции
`pachca link-previews add`	POSTUnfurl (разворачивание ссылок)
`pachca search list-chats`	GETПоиск чатов
`pachca search list-messages`	GETПоиск сообщений
`pachca search list-users`	GETПоиск сотрудников
`pachca tasks create`	POSTНовое напоминание
`pachca tasks list`	GETСписок напоминаний
`pachca tasks get`	GETИнформация о напоминании
`pachca tasks update`	PUTРедактирование напоминания
`pachca tasks delete`	DELETEУдаление напоминания
`pachca views open`	POSTОткрытие представления
`pachca bots list-events`	GETИстория событий
`pachca bots update`	PUTРедактирование бота
`pachca bots remove-event`	DELETEУдаление события
`pachca security list`	GETЖурнал аудита событий

Справка

# Подробная справка по командеpachca messages create --help # Список всех командpachca commands # Только команды, доступные текущему токену (фильтр по скоупам)pachca commands --available

Вывод

Форматы

CLI поддерживает четыре формата вывода. В интерактивном терминале (TTY) по умолчанию используется таблица, в пайпах и CI — JSON.

# Таблица (по умолчанию в терминале)pachca users list # JSONpachca users list -o json # YAMLpachca users list -o yaml # CSV (для Excel / Google Sheets)pachca users list -o csv

Колонки и заголовки

По умолчанию таблица показывает 4-5 основных полей. Выбрать конкретные колонки:

# Выбрать колонкиpachca users list --columns id,email,role # Без заголовка (для скриптов)pachca users list --columns email --no-header # Не обрезать длинные значенияpachca users list --no-truncate

Пайпы и перенаправление

В пайпах CLI автоматически выводит JSON и отключает цвет и спиннер. Данные идут в stdout, ошибки и прогресс — в stderr.

# Передать в jqpachca users list | jq '.[].name' # Текст сообщения из файлаpachca messages create --entity-id 123 < message.txt # Текст из pipeecho "Деплой завершён" | pachca messages create --entity-id 123 # Скачать файл (для команд с редиректом)pachca common get-exports 123 --save ./export.zip

Пагинация

Pachca использует cursor-based пагинацию. CLI предоставляет три способа навигации:

# Первая страница (по умолчанию)pachca users list --limit 20 # Следующая страница вручнуюpachca users list --cursor eyJpZCI6NTB9 # Загрузить все страницы автоматическиpachca users list --all

При --all CLI показывает прогресс загрузки в stderr, а финальный результат выводит в stdout единым массивом.

Загрузка файлов

Команда pachca upload автоматически получает подпись через POST /uploads и загружает файл на S3 — не нужно вручную копировать 7 параметров подписи:

# Загрузить файлpachca upload photo.jpg # Из stdincat data.csv | pachca upload -

Команда возвращает key — используйте его в поле files[].key при создании сообщений:

# Загрузить файл и отправить в чатKEY=$(pachca upload photo.jpg -o json | jq -r '.key')pachca messages create --entity-id 123 --content "Фото" --files "[{\"key\":\"$KEY\",\"name\":\"photo.jpg\"}]"

Для низкоуровневого контроля доступна команда pachca common direct-url — она отправляет multipart-запрос на указанный URL с параметрами подписи.

Сценарии

CLI включает готовые пошаговые сценарии для типичных задач. Каждый сценарий — это последовательность команд с комментариями: какой метод вызвать, какие параметры передать, на что обратить внимание. Не знаете, какую команду использовать — поищите по задаче:

# Поиск сценариев по ключевым словамpachca guide "отправить файл"pachca guide "создать беседу и добавить участников" # Список всех сценариевpachca guide

Примеры сценариев

pachca guide "создать напоминание" #  Сценарий: Создать напоминание  (pachca-tasks)##  1. $ pachca tasks create --kind=reminder --content="Позвонить клиенту" --due-at=<дата> --chat-id=<chat_id> pachca guide "кастомные поля профиля" #  Сценарий: Получить кастомные поля профиля  (pachca-profile)##  1. $ pachca common custom-properties  # entity_type=User#  2. $ pachca profile get  # custom_properties содержит значения полей pachca guide "активные чаты" #  Сценарий: Найти активные чаты за период  (pachca-chats)##  1. $ pachca chats list --last-message-at-after=<дата> --all

Скрипты и CI

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

Флаг	Короткий	Описание
`--output <format>`	`-o`	Формат: `table`, `json`, `yaml`, `csv`
`--columns <list>`	`-c`	Колонки для table-вывода (через запятую)
`--profile <name>`	`-p`	Профиль для этой команды
`--token <value>`		Токен для этого вызова (без сохранения)
`--quiet`	`-q`	Без вывода, только exit code
`--no-input`		Без интерактивных промптов
`--dry-run`		Показать запрос без отправки
`--force`		Пропустить подтверждение DELETE
`--verbose`	`-v`	Показать HTTP-запросы и ответы
`--timeout <sec>`		Таймаут запроса в секундах (по умолчанию 30)
`--no-color`		Отключить цвета
`--no-header`		Скрыть заголовок таблицы
`--no-truncate`		Не обрезать длинные значения
`--no-retry`		Отключить авто-retry при 429/503

Сортировка

Команды списков поддерживают сортировку через --sort и --order:

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

Доступные поля сортировки зависят от команды — подсказки встроены в --help. Если --order не указан, используется desc.

Имена флагов

Флаги CLI используют kebab-case (через дефис), а не snake_case как в API-документации — это стандартная конвенция для CLI-инструментов:

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. Проверить можно через --dry-run:

pachca users update 123 --first-name "Иван" --phone-number "+7900" --dry-run # {"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

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

Флаг --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": "Привет"}}

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

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

# С подтверждением (TTY)pachca users delete 1234 # Без подтвержденияpachca users delete 1234 --force

Exit codes

Код	Значение
`0`	Успех
`1`	API или runtime ошибка
`2`	Неверные флаги или аргументы
`3`	Ошибка аутентификации (401 / 403)
`4`	Ресурс не найден (404)

Использование exit codes

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

Ошибки

При -o json (или в пайпе) ошибки выводятся в stderr как JSON. Формат единый для всех типов ошибок:

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": "обязательное поле" }  ]}

Ошибка авторизации

{  "error": "Token not found",  "code": null,  "type": "PACHCA_AUTH_ERROR",  "hint": "pachca auth login --token <your-token>"}

Поле	Тип	Описание
`error`	`string`	Сообщение об ошибке
`code`	`number \| null`	HTTP-код ответа (`null` для клиентских ошибок)
`type`	`string`	Тип ошибки (см. таблицу ниже)
`request_id`	`string?`	ID запроса к API (для обращения в поддержку)
`hint`	`string?`	Подсказка, как исправить ошибку
`field`	`string?`	Поле, вызвавшее ошибку
`errors`	`array?`	Список ошибок при множественной валидации

Тип	Описание
`PACHCA_API_ERROR`	Ошибка API (5xx, неожиданные ответы)
`PACHCA_AUTH_ERROR`	Ошибка аутентификации (401 / 403)
`PACHCA_VALIDATION_ERROR`	Ошибка валидации (422)
`PACHCA_SCOPE_ERROR`	Токен не имеет нужного скоупа
`PACHCA_NETWORK_ERROR`	Сеть недоступна
`PACHCA_TIMEOUT_ERROR`	Таймаут запроса
`PACHCA_USAGE_ERROR`	Неверные флаги или аргументы

Обработка ошибок в скрипте

# Получить ошибку как 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_TOKEN`	Bearer-токен (высший приоритет, удобно для CI)
`PACHCA_PROFILE`	Активный профиль для команды
`PACHCA_TIMEOUT`	Таймаут запроса в секундах (по умолчанию 30)
`PACHCA_PROMPT_DISABLED`	Отключить интерактивные промпты (для агентов)
`CI`	Автоматический неинтерактивный режим
`NO_COLOR`	Отключить цвет
`FORCE_COLOR`	Принудительно включить цвет
`PACHCA_SKIP_NEW_VERSION_CHECK`	Отключить проверку обновлений

Неинтерактивный режим

CLI автоматически переходит в неинтерактивный режим при любом из условий: stdin или stdout — не TTY, установлена PACHCA_PROMPT_DISABLED или CI, передан флаг --no-input. В этом режиме нет промптов, спиннера, а при пропущенных обязательных флагах — ошибка вместо запроса.

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

Прямые API-запросы

Команда pachca api — escape hatch для прямых HTTP-запросов без типизированных команд:

# GET с query paramspachca api GET /messages --query chat_id=123 # POST с типизированными полями (-F конвертирует числа и boolean)pachca api POST /messages -F message[entity_id]=12345 -f message[content]="Привет" # PUT со строковым полем (-f гарантирует string)pachca api PUT /tasks/42 -f task[due_at]="2026-04-01T10:00:00Z" # Отправить готовый JSON-файлpachca api POST /messages --input payload.json # Из stdincat payload.json | pachca api POST /messages --input -

pachca api выводит сырой ответ API без извлечения данных из обёртки data

Настройки

Установите постоянные значения по умолчанию:

# Всегда выводить JSONpachca config set defaults.output json # Увеличить таймаутpachca config set defaults.timeout 60 # Показать все настройкиpachca config list

Настройки хранятся в ~/.config/pachca/config.toml. Флаги команды всегда имеют приоритет над настройками.

Автодополнение

CLI поддерживает автодополнение для bash, zsh и fish:

pachca autocomplete zshpachca autocomplete bashpachca autocomplete fish

Команда выводит инструкцию по установке для выбранного шелла.

Диагностика

Команда pachca doctor проверяет окружение — Node.js, сеть, конфиг, токен и версию CLI:

pachca doctor # ✔ Node.js        v20.11.0 (требуется >=20)# ✔ Сеть           api.pachca.com доступен (142ms)# ✔ Конфиг         ~/.config/pachca/config.toml (права: 600)# ✔ Профиль        personal (user: Иван Иванов)# ✔ Токен          действителен (11 скоупов)# ✔ CLI            v2026.3.0 (актуальная версия)

Обновление

CLI автоматически проверяет наличие новой версии раз в сутки и показывает уведомление в терминале. Для обновления:

# Обновить до последней версииpachca upgrade # Или вручную через npmnpm install -g @pachca/cli # Посмотреть, что новогоpachca changelog

Отключить автоматическую проверку можно переменной PACHCA_SKIP_NEW_VERSION_CHECK.