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

Вывод

Форматы вывода

CLI поддерживает четыре формата вывода. Формат задаёт флаг -o, без него — настройка defaults.output из конфига. Если не задано ни то ни другое, в интерактивном терминале (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

Те же колонки по умолчанию выводят CSV и --plain: чтобы выгрузить другие поля, перечислите их в --columns. JSON и YAML выводят объект целиком, --columns на них не действует.

Плоский вывод

Флаг --plain — именованный режим для скриптов: TSV (значения через таб), без заголовка, без цвета и обрезки. Без --columns колонки те же, что в таблице, и id, если оно есть, идёт первым. Удобно для cut/awk вместо комбинации --columns ... --no-header -o csv:

# id <tab> title <tab> first_name <tab> last_name <tab> emailpachca users list --plain # Почта каждого сотрудника: вторая из выбранных колонокpachca users list --plain --columns id,email | cut -f2 # Выбранные колонки идут в заданном порядкеpachca users list --plain --columns email,role

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

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

# Передать в jq: имя и фамилия каждого сотрудникаpachca users list | jq -r '.[] | "\(.first_name) \(.last_name)"' # Текст сообщения из файлаpachca messages create --entity-id 123 < message.txt # Текст из pipeecho "Деплой завершён" | pachca messages create --entity-id 123 # Скачать файл (для команд с редиректом)pachca chats download-export 123 --save ./export.zip

Пагинация

Пагинация в API курсорная. Команды списков принимают флаги --limit, --cursor и --all:

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

При --all CLI проходит все страницы сам и выводит записи в stdout единым массивом. В терминале он показывает прогресс загрузки в stderr. Больше 500 страниц --all не загружает: на этом команда останавливается с предупреждением «Достигнут лимит 500 страниц» в stderr и завершается с кодом 0. Для больших выгрузок задайте наибольший --limit, который допускает метод.

Без --all команда выводит только записи страницы, массив data. Блок meta с курсорами она не показывает, поэтому курсор следующей страницы берут из полного ответа прямого запроса pachca api:

# Полный ответ с meta: курсор следующей страницыpachca api GET /users --query limit=20 | jq -r '.meta.paginate.next_page' # Следующая страница по этому курсоруpachca users list --limit 20 --cursor <next_page>

Курсор следующей страницы у всех методов лежит в meta.paginate.next_page, а признак последней страницы — meta.paginate.has_next: false. Чем отличаются ответы списочных методов и методов поиска, описано в разделе Две группы методов с пагинацией.