@pachca/cli 2026.10.2 → 2026.10.4

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 2026.10.4  (31 октября 2026)
+
+- **Исправлено** (api): Справка `--docs` и схема `--spec` показывают `dlp_rule_id` в деталях события `dlp_violation_detected` строкой, как его отдаёт API
+- **Добавлено** (upload): Флаг `--name` задаёт имя файла, которым заканчивается `key`: так данные из stdin получают расширение и уходят в сообщение под этим именем
+- **Исправлено** (upload): Файл, которого нет на диске, команда отклоняет до запроса подписи, в том числе с `--dry-run`
+- **Изменено** (doctor): Проверяет тот же токен, что и остальные команды, в том же порядке: `--token`, `--profile`, `PACHCA_TOKEN`, `PACHCA_PROFILE`, активный профиль, поэтому в CI с одной `PACHCA_TOKEN` команда проходит
+- **Изменено** (doctor): При ошибке хотя бы одной проверки команда завершается с кодом `1` в любом формате вывода, в том числе с `-o json`
+- **Изменено** (doctor): Без файла конфига команда показывает путь, по которому его ищет
+- **Исправлено**: `--dry-run` показывает запрос без входа и без `PACHCA_TOKEN`, а токен в заголовке `Authorization` заменён маской
+- **Исправлено** (files direct-url): С `--dry-run` запрос показан без заголовка `Authorization`, как он и уходит в хранилище
+- **Изменено** (bots update, drafts update): Слово `null` во флаге поля, которое принимает `null`, уходит в API как JSON null: `--kind null` удаляет входящий вебхук бота, а `--parent-message-id null` снимает ответ с черновика
+- **Исправлено** (auth login): Вход через браузер с `--quiet` печатает адрес и код подтверждения, а флаг убирает только строку ожидания и отчёт о входе
+- **Изменено** (auth login): Пример в `--help` и подсказка при `--token -` без потока ввода передают токен из буфера обмена: `pbpaste | pachca auth login --token -`
+- **Исправлено** (messages create, messages update, drafts create, drafts update, tasks create, tasks update): Текст из потока ввода попадает в запрос, только когда поток не пуст, а с пустым потоком, как у скрипта или агента, команда отправляет поля из флагов
+- **Изменено**: Отказ `403` с `role_forbidden` в терминале объясняется словами: право у токена есть, но действие не разрешает роль, поэтому новый вход или токен не помогут. Вывод с `-o json` и в пайпе прежний.
+- **Изменено**: Объяснение отказа `insufficient_scope` в терминале зависит от источника токена: с `--token` или `PACHCA_TOKEN` команда предлагает `pachca oauth token-info -o json`, а если право есть в сохранённом списке профиля, советует обновить его через `pachca auth status --remote`
+- **Изменено**: Когда вход через браузер завершён или отозван, сообщение и подсказка `pachca auth login` называют профиль, с которым шла команда
+- **Исправлено** (api): Эквивалентная команда в справке `--describe` повторяет пример запроса из спецификации и работает при копировании
+- **Исправлено** (api): Пример `pachca api POST /messages` в `--help` передаёт `message[entity_id]` в кавычках и работает при копировании, а описание команды и ошибка `--describe` для неизвестного пути говорят «метод»
+- **Изменено** (views open): Выводит ответ API `{ "success": true }`
+- **Изменено**: Справка команд следует обновлённым описаниям API: удаление входящего вебхука, правило совпадения команд бота, правило упоминаний в тексте сообщения, `duration_ms` и `file_type` у файлов, срок ссылки на поток событий, напоминания вместо задач, поле `scopes` у `bot_token_updated` и другие поля деталей журнала аудита, значения настройки бота у `restricted_bot_tag_denied` в подсказке `--list-tags`, добавление участников в тред, создание треда, `--skip-invite-mentions`, правка без уведомления и список прочитавших
+- **Исправлено** (api): Справка `--docs` и схема `--spec` описывают `scopes` в деталях бота журнала аудита так, как его писал API до 7 октября 2026 года: список прав у `bot_token_created` и объект с `previous` и `new` у `bot_token_updated`
+- **Изменено** (search): С `--all` команды поиска останавливаются по `has_next` и показывают в терминале, сколько результатов загружено из общего числа найденных
+- **Изменено** (api): Справка `--docs` и схема `--spec` методов поиска показывают поле `has_next` в `meta.paginate`
+
+## 2026.10.3  (28 октября 2026)
+
+- **Изменено** (guide): Команда убрана вместе со сценариями: как решать задачи в Пачке, агенту рассказывают скиллы (https://dev.pachca.com/guides/mcp/plugin), а флаги каждой команды показывает `pachca <команда> --help`
+- **Изменено**: Из `--help` команд убран блок примеров со сценариями
+- **Изменено** (api): `api ls` и справка `--describe`, `--spec`, `--docs` работают без токена: они читают встроенную спецификацию и в API не обращаются
+- **Добавлено** (important-messages list, important-messages create, important-messages delete): Новые команды — раздел «Важное» владельца токена: список отмеченных сообщений, добавление сообщения и удаление из раздела
+- **Добавлено** (bots get-stream): Новая команда — ссылка на поток событий бота
+- **Добавлено** (users update): Значение `guest` у `--role` вместе с флагом `--chat-ids` переводит сотрудника в гости
+- **Добавлено** (chats create): Команда предупреждает в stderr об идентификаторах из `--group-tag-ids`, которых нет среди тегов пространства
+- **Добавлено**: В выводе команд с сообщениями появилось поле `important`: сообщение в разделе «Важное» владельца токена
+- **Изменено** (auth logout): После входа через браузер команда закрывает вход на сервере и при истёкшем токене: сначала обновляет его, потом отзывает свежий
+- **Изменено** (auth logout): `token_revoked: true` значит, что вход на сервере закрыт, в том числе если его закрыли раньше, а при `false` закрыть вход не удалось, и его нужно отозвать в списке «Токены CLI»
+- **Изменено**: Ответы `500`, `502`, `503`, `504` и сетевую ошибку CLI повторяет до трёх раз только у запросов GET, PUT и DELETE, POST и PATCH после них не повторяются, а `504` с кодом `timeout` (поиск не уложился по времени) приходит ошибкой сразу
+- **Изменено**: Подсказки при опечатке в команде предлагают только существующие команды, без `pachca skill …`
+- **Исправлено**: Описание флага `--no-retry` уточнено: он отключает повторы после `429`, `5xx` и сетевой ошибки
+
 ## 2026.10.2  (21 октября 2026)
 
 - **Добавлено** (security list): Флаг `--event-key` принимает события входа по QR-коду: `login_grant_created`, `login_grant_approved` и `login_grant_denied`

package/README.md

@@ -14,31 +14,33 @@ npx -y @pachca/cli users list
 ## Быстрый старт
 
 ```
-pachca auth login          # сохранить токен
+pachca auth login          # вход через браузер
 pachca users list          # список сотрудников
 pachca messages create --entity-id 123 --content "Привет!"
 ```
 
-Получить токен: https://dev.pachca.com/guides/authorization
+Какой токен выбрать: https://dev.pachca.com/api/authorization
 
 ## Использование в агентах (Claude, Cursor и др.)
 
-Если агент устанавливает CLI по просьбе пользователя и токена ещё нет — агент должен запросить его у пользователя:
+Вход запускает сотрудник в своём терминале командой `pachca auth login` и подтверждает в браузере. Агент проверяет вход командой `pachca auth status`. Токен в разговоре агенту не передают.
 
 ```
-# Агент спрашивает: "Нужен API-токен Пачки."
-# "Получите его на https://dev.pachca.com/guides/authorization"
-pachca auth login --token <токен от пользователя>
+pachca auth status                       # есть ли вход и под кем
+pachca api ls                            # справка по API без входа и без токена
+pachca api POST /messages --describe
+```
 
-# Дальше команды работают без токена в каждой строке
-pachca users list
-pachca messages create --entity-id 123 --content "Привет!"
+В CI и у агентов без сотрудника токен приходит из переменной окружения, `auth login` не нужен:
+
+```
+PACHCA_TOKEN=$TOKEN pachca users list --no-input
 ```
 
-Если токен уже есть в окружении — `auth login` не нужен:
+Готовый токен сохраняют через stdin, а не аргументом: аргумент остаётся в истории оболочки и в списке процессов.
 
 ```
-PACHCA_TOKEN=$TOKEN pachca users list
+pbpaste | pachca auth login --token -
 ```
 
 ## Профили (несколько токенов)
@@ -52,18 +54,7 @@ pachca auth list
 pachca auth switch bot-notify
 ```
 
-Токены хранятся в `~/.config/pachca/config.toml` (chmod 600).
-В CI — через переменную окружения PACHCA_TOKEN.
-
-## Поиск по сценариям
-
-Не знаете какую команду использовать? Поищите по задаче:
-
-```
-pachca guide "отправить файл"
-pachca guide "создать беседу и добавить участников"
-pachca guide            # список всех сценариев
-```
+Токен хранится в хранилище ключей ОС, в `~/.config/pachca/config.toml` только имя, почта и права. Где хранилища нет, токен лежит в этом файле, CLI говорит об этом при входе.
 
 <!-- AUTO:COMMANDS -->
 ## Команды
@@ -97,6 +88,7 @@ pachca guide            # список всех сценариев
 | `pachca bots reissue-token` | Перевыпуск токена бота |
 | `pachca bots list-company` | Список ботов пространства |
 | `pachca bots list-events` | История событий |
+| `pachca bots get-stream` | Поток событий |
 | `pachca bots remove-event` | Удаление события истории |
 
 ### chats
@@ -163,6 +155,14 @@ pachca guide            # список всех сценариев
 | `pachca group-tags delete` | Удаление тега |
 | `pachca group-tags list-users` | Список сотрудников тега |
 
+### important-messages
+
+| Команда | Описание |
+|---------|---------|
+| `pachca important-messages list` | Список важных сообщений |
+| `pachca important-messages create` | Добавление сообщения в важные |
+| `pachca important-messages delete` | Удаление сообщения из важных |
+
 ### messages
 
 | Команда | Описание |
@@ -275,7 +275,7 @@ pachca guide            # список всех сценариев
 | `--no-input` |  | Отключить интерактивные промпты |
 | `--dry-run` |  | Показать запрос без отправки |
 | `--timeout <value>` |  | Таймаут запроса в секундах (по умолчанию 30) |
-| `--no-retry` |  | Отключить авто-retry при 429/503 |
+| `--no-retry` |  | Отключить автоповтор при 429, 5xx и сетевых ошибках |
 | `--plain` |  | Плоский вывод: TSV без заголовка, ID первым, без цвета (для скриптов) |
 
 <!-- AUTO:FLAGS:END -->
@@ -286,11 +286,11 @@ pachca guide            # список всех сценариев
 # Загрузить файл (получает подпись и загружает автоматически)
 pachca upload photo.jpg
 
-# Из stdin
-cat data.csv | pachca upload -
+# Из stdin: имя с расширением задаёт --name
+cat data.csv | pachca upload - --name data.csv
 ```
 
-Команда `upload` автоматически получает подпись (`POST /uploads`) и загружает файл на S3. Возвращает `key` — используйте его в `--files` при создании сообщений.
+Команда `upload` автоматически получает подпись (`POST /uploads`) и загружает файл на S3. Возвращает `key` — используйте его в `--files` при создании сообщений. Расширение `name` в файле сообщения должно совпадать с расширением имени в `key`.
 
 ## Пагинация
 
@@ -340,7 +340,7 @@ pachca users list --columns id,email,role
 pachca users list --columns email --no-header
 
 # Пайп — цвет отключается автоматически
-pachca users list -o json | jq '.[].name'
+pachca users list -o json | jq -r '.[] | "\(.first_name) \(.last_name)"'
 
 # Текст из файла или pipe
 pachca messages create --entity-id 123 < message.txt
@@ -373,7 +373,7 @@ Escape hatch для нестандартных запросов без сген
 
 ```
 pachca api GET /messages --query chat_id=123
-pachca api POST /messages -F message[chat_id]=12345 -f message[content]="Привет"
+pachca api POST /messages -F 'message[entity_id]=12345' -f 'message[content]=Привет'
 pachca api POST /messages --input payload.json
 pachca api GET /profile -o yaml --dry-run
 ```

package/README.template.md

@@ -14,31 +14,33 @@ npx -y @pachca/cli users list
 ## Быстрый старт
 
 ```
-pachca auth login          # сохранить токен
+pachca auth login          # вход через браузер
 pachca users list          # список сотрудников
 pachca messages create --entity-id 123 --content "Привет!"
 ```
 
-Получить токен: https://dev.pachca.com/guides/authorization
+Какой токен выбрать: https://dev.pachca.com/api/authorization
 
 ## Использование в агентах (Claude, Cursor и др.)
 
-Если агент устанавливает CLI по просьбе пользователя и токена ещё нет — агент должен запросить его у пользователя:
+Вход запускает сотрудник в своём терминале командой `pachca auth login` и подтверждает в браузере. Агент проверяет вход командой `pachca auth status`. Токен в разговоре агенту не передают.
 
 ```
-# Агент спрашивает: "Нужен API-токен Пачки."
-# "Получите его на https://dev.pachca.com/guides/authorization"
-pachca auth login --token <токен от пользователя>
+pachca auth status                       # есть ли вход и под кем
+pachca api ls                            # справка по API без входа и без токена
+pachca api POST /messages --describe
+```
+
+В CI и у агентов без сотрудника токен приходит из переменной окружения, `auth login` не нужен:
 
-# Дальше команды работают без токена в каждой строке
-pachca users list
-pachca messages create --entity-id 123 --content "Привет!"
+```
+PACHCA_TOKEN=$TOKEN pachca users list --no-input
 ```
 
-Если токен уже есть в окружении — `auth login` не нужен:
+Готовый токен сохраняют через stdin, а не аргументом: аргумент остаётся в истории оболочки и в списке процессов.
 
 ```
-PACHCA_TOKEN=$TOKEN pachca users list
+pbpaste | pachca auth login --token -
 ```
 
 ## Профили (несколько токенов)
@@ -52,18 +54,7 @@ pachca auth list
 pachca auth switch bot-notify
 ```
 
-Токены хранятся в `~/.config/pachca/config.toml` (chmod 600).
-В CI — через переменную окружения PACHCA_TOKEN.
-
-## Поиск по сценариям
-
-Не знаете какую команду использовать? Поищите по задаче:
-
-```
-pachca guide "отправить файл"
-pachca guide "создать беседу и добавить участников"
-pachca guide            # список всех сценариев
-```
+Токен хранится в хранилище ключей ОС, в `~/.config/pachca/config.toml` только имя, почта и права. Где хранилища нет, токен лежит в этом файле, CLI говорит об этом при входе.
 
 <!-- AUTO:COMMANDS -->
 <!-- AUTO:COMMANDS:END -->
@@ -77,11 +68,11 @@ pachca guide            # список всех сценариев
 # Загрузить файл (получает подпись и загружает автоматически)
 pachca upload photo.jpg
 
-# Из stdin
-cat data.csv | pachca upload -
+# Из stdin: имя с расширением задаёт --name
+cat data.csv | pachca upload - --name data.csv
 ```
 
-Команда `upload` автоматически получает подпись (`POST /uploads`) и загружает файл на S3. Возвращает `key` — используйте его в `--files` при создании сообщений.
+Команда `upload` автоматически получает подпись (`POST /uploads`) и загружает файл на S3. Возвращает `key` — используйте его в `--files` при создании сообщений. Расширение `name` в файле сообщения должно совпадать с расширением имени в `key`.
 
 ## Пагинация
 
@@ -131,7 +122,7 @@ pachca users list --columns id,email,role
 pachca users list --columns email --no-header
 
 # Пайп — цвет отключается автоматически
-pachca users list -o json | jq '.[].name'
+pachca users list -o json | jq -r '.[] | "\(.first_name) \(.last_name)"'
 
 # Текст из файла или pipe
 pachca messages create --entity-id 123 < message.txt
@@ -164,7 +155,7 @@ Escape hatch для нестандартных запросов без сген
 
 ```
 pachca api GET /messages --query chat_id=123
-pachca api POST /messages -F message[chat_id]=12345 -f message[content]="Привет"
+pachca api POST /messages -F 'message[entity_id]=12345' -f 'message[content]=Привет'
 pachca api POST /messages --input payload.json
 pachca api GET /profile -o yaml --dry-run
 ```

package/dist/base-command.js

@@ -1,5 +1,5 @@
 import { Command, Flags } from '@oclif/core';
-import { resolveToken, TokenNotFoundError, ProfileNotFoundError, getAuthMethod, getDefaults, } from './profiles.js';
+import { resolveToken, TokenNotFoundError, ProfileNotFoundError, getAuthMethod, getDefaults, profileFlag, } from './profiles.js';
 import { ApiError, getExitCode, formatDryRun, request } from './client.js';
 import { outputData, outputError, outputSuccess } from './output.js';
 import { defaultOutputFormat, isInteractive } from './utils.js';
@@ -57,7 +57,7 @@ export class BaseCommand extends Command {
             min: 1,
         }),
         'no-retry': Flags.boolean({
-            description: 'Disable auto-retry on 429/503',
+            description: 'Disable auto-retry on 429, 5xx and network errors',
             default: false,
         }),
         json: Flags.boolean({
@@ -181,8 +181,10 @@ export class BaseCommand extends Command {
      * Make an authenticated API request.
      */
     async apiRequest(opts) {
-        const { token } = this.resolveAuth();
         const clientFlags = this.getClientFlags();
+        // --dry-run sends nothing, so it needs no token: the preview masks the header
+        // either way. Resolving first made it fail with «Token not found» before login.
+        const token = clientFlags['dry-run'] ? '' : this.resolveAuth().token;
         const fullOpts = { ...opts, token };
         if (clientFlags['dry-run']) {
             const dryRunOutput = formatDryRun(fullOpts, this.getOutputFormat() === 'json');
@@ -235,9 +237,11 @@ export class BaseCommand extends Command {
      * Explain a scope refusal instead of printing a bare 403.
      *
      * An agent cannot walk through a consent screen — the most useful thing it can
-     * do is hand control back to a human with the reason spelled out. The reason
-     * differs by how the profile was authorised: an OAuth login already asks for
-     * every scope, so a refusal there can only come from the role.
+     * do is hand control back to a human with the reason spelled out.
+     *
+     * `insufficient_scope` always means the token itself lacks the scope. A role
+     * that does not allow the action comes back as `role_forbidden` instead, see
+     * reportRoleRefusal. The fix differs by how the profile was authorised.
      */
     reportScopeError(err) {
         const format = this.getOutputFormat();
@@ -246,44 +250,69 @@ export class BaseCommand extends Command {
             outputError(err.details, format);
             this.exit(3);
         }
-        let profile;
-        try {
-            ({ profile } = resolveToken({
-                token: this.parsedFlags.token,
-                profile: this.parsedFlags.profile,
-            }));
+        const resolved = this.tryResolveProfile();
+        const profile = resolved?.profile;
+        process.stderr.write(`✗ Не хватает права${scope ? ` ${scope}` : ''}.\n`);
+        if (!profile) {
+            process.stderr.write(`  У токена ${scope ? 'этого' : 'нужного'} права нет.\n`);
+            process.stderr.write(`  Проверить права токена: pachca oauth token-info -o json\n`);
+            this.exit(3);
         }
-        catch {
-            // no profile resolved — the token came in from a flag or the environment
+        // The scope list in the profile is a copy taken at login. When it still names
+        // the scope the server just refused, the copy is stale: the token's scopes were
+        // changed after login. Naming the scope needs the server's message to carry it.
+        const flag = profileFlag(resolved?.profileName);
+        const listedLocally = !!scope && !!profile.scopes?.includes(scope);
+        if (listedLocally) {
+            process.stderr.write(`  В сохранённом списке право есть, но у токена его уже нет: список устарел.\n`);
+            process.stderr.write(`  Обновить список: pachca auth status --remote${flag}\n`);
         }
-        // Two different causes, and the fix differs. Either the scope is not in the
-        // token, or it is there but the role no longer allows it — the API checks
-        // both on every call. Which one it is shows in the token's own scope list.
-        //
-        // Naming the cause needs the scope itself, and that comes from parsing the
-        // server's message. When it cannot be identified, fall back to the generic
-        // wording: guessing a branch here would send people to fix the wrong thing.
-        const granted = scope ? profile?.scopes : undefined;
-        const hasScope = !!scope && !!granted && granted.includes(scope);
-        process.stderr.write(`✗ Не хватает права${scope ? ` ${scope}` : ''}.\n`);
-        if (granted && hasScope) {
-            process.stderr.write(`  Право у токена есть, но его не даёт текущая роль.\n`);
-            process.stderr.write(`  Обратитесь к администратору пространства.\n`);
+        else {
+            process.stderr.write(`  У токена ${scope ? 'этого' : 'нужного'} права нет.\n`);
+        }
+        if (getAuthMethod(profile) === 'oauth') {
+            process.stderr.write(`  При входе через браузер права выдаются по роли на момент подтверждения.\n`);
+            process.stderr.write(`  Если роль с тех пор расширили, войдите заново: pachca auth login${flag}\n`);
+        }
+        else {
+            process.stderr.write(`  Добавьте право токену в Пачке или выпустите новый токен с ним.\n`);
+        }
+        this.exit(3);
+    }
+    /**
+     * Explain a role refusal: the token carries the scope, but the role of the
+     * account behind it does not allow the action. No new login or token changes
+     * that, so say who can. The API names no scope here; a generated command
+     * knows the one its method requires.
+     */
+    reportRoleRefusal(err) {
+        const format = this.getOutputFormat();
+        if (format === 'json' || !process.stderr.isTTY) {
+            outputError(err.details, format);
+            this.exit(3);
         }
-        else if (granted) {
-            process.stderr.write(`  У токена этого права нет.\n`);
-            process.stderr.write(getAuthMethod(profile) === 'oauth'
-                ? `  Права выдаются по роли в момент входа — если роль с тех пор изменилась, войдите заново: pachca auth login\n`
-                : `  Выпустите токен с этим правом в интерфейсе Пачки.\n`);
+        const profile = this.tryResolveProfile()?.profile;
+        const scope = this.constructor.scope;
+        const right = scope ? `Право ${scope}` : 'Право';
+        if (profile?.type === 'bot') {
+            process.stderr.write(`✗ ${right} есть у токена, но его не даёт роль бота.\n`);
+            process.stderr.write(`  Это действие выполняют персональным токеном сотрудника с подходящей ролью.\n`);
         }
         else {
-            process.stderr.write(`  Либо этого права нет у токена, либо его не даёт ваша роль.\n`);
-            process.stderr.write(profile
-                ? `  Проверить права токена: pachca auth status\n`
-                : `  Проверить права токена: pachca api GET /oauth/token/info\n`);
+            process.stderr.write(`✗ ${right} есть у токена, но его не даёт роль.\n`);
+            process.stderr.write(`  Новый вход или новый токен не помогут: роль меняет администратор пространства.\n`);
         }
         this.exit(3);
     }
+    /** The profile the call ran with, or undefined when the token came from --token or PACHCA_TOKEN. */
+    tryResolveProfile() {
+        try {
+            return resolveToken({ token: this.parsedFlags.token, profile: this.parsedFlags.profile });
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * What to do after a 401: the login was revoked, or the saved token no longer works.
      *
@@ -306,7 +335,7 @@ export class BaseCommand extends Command {
                 ? 'Токен из --token или PACHCA_TOKEN недействителен или отозван.'
                 : 'token from --token or PACHCA_TOKEN is invalid or revoked';
         }
-        const flag = resolved.profileName === 'default' ? '' : ` --profile ${resolved.profileName}`;
+        const flag = profileFlag(resolved.profileName);
         if (getAuthMethod(resolved.profile) === 'oauth') {
             return human
                 ? `Вход завершён или отозван. Войдите заново: pachca auth login${flag}`
@@ -323,6 +352,9 @@ export class BaseCommand extends Command {
         if (err instanceof ApiError && err.details.type === 'PACHCA_SCOPE_ERROR') {
             this.reportScopeError(err);
         }
+        if (err instanceof ApiError && err.details.code === 403 && err.details.message === 'role_forbidden') {
+            this.reportRoleRefusal(err);
+        }
         if (err instanceof ApiError) {
             if (err.details.code === 401 && !err.details.hint) {
                 err.details.hint = this.reloginHint();

package/dist/client.js

@@ -24,6 +24,11 @@ export function getBaseUrl() {
 }
 const MAX_RETRIES = 3;
 const DEFAULT_TIMEOUT = 30;
+const RETRYABLE_5XX = new Set([500, 502, 503, 504]);
+// A 5xx says nothing about whether the server already applied the request, and
+// the API has no idempotency key: a retried POST /messages sends the message
+// twice. These methods are safe to repeat, the same set as in the SDKs.
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
 function buildUrl(apiPath, query) {
     const base = apiPath.startsWith('http://') || apiPath.startsWith('https://')
         ? apiPath
@@ -52,7 +57,8 @@ function maskToken(token) {
 export function formatDryRun(opts, isJson) {
     const url = buildUrl(opts.path, opts.query);
     const headers = {
-        Authorization: `Bearer ${maskToken(opts.token)}`,
+        // The real request carries the token; the preview never shows it, and works without one.
+        ...(opts.noAuth ? {} : { Authorization: `Bearer ${maskToken(opts.token)}` }),
         ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
         ...opts.headers,
     };
@@ -101,9 +107,11 @@ export async function request(opts, clientFlags) {
     // means by `--timeout 0`. The env var already ignored 0; make the flag agree.
     const timeoutSeconds = requestedTimeout > 0 ? requestedTimeout : DEFAULT_TIMEOUT;
     const noRetry = opts.noRetry ?? clientFlags?.['no-retry'] ?? false;
-    // Retrying a request the server may already have committed duplicates it.
-    // Only these methods are safe to repeat blindly.
-    const safeMethod = ['GET', 'HEAD', 'OPTIONS', 'PUT'].includes(opts.method);
+    const method = opts.method.toUpperCase();
+    // The same set is retried after a 5xx and after a network error. A repeated
+    // DELETE whose first attempt went through answers 404, which the caller sees
+    // as an error, but it never deletes anything twice.
+    const idempotent = IDEMPOTENT_METHODS.has(method);
     const fetchHeaders = {
         ...(opts.noAuth ? {} : { Authorization: `Bearer ${opts.token}` }),
         Accept: 'application/json',
@@ -178,35 +186,32 @@ export async function request(opts, clientFlags) {
                     continue;
                 }
             }
-            // Handle 503 with backoff. Unlike 429, a 503 from a proxy or a draining
-            // load balancer says nothing about whether the backend already committed
-            // the write — retrying a POST there duplicates the message.
-            if (response.status === 503 && safeMethod && !noRetry && attempt < MAX_RETRIES) {
-                const baseMs = 1000;
-                const waitMs = baseMs * Math.pow(2, attempt) + Math.random() * baseMs;
-                if (clientFlags?.verbose) {
-                    process.stderr.write(`${ansis.dim(`⏳ Service unavailable, retrying in ${Math.round(waitMs)}ms...`)}\n`);
-                }
-                await sleep(waitMs);
-                continue;
-            }
-            // Parse response body
-            const contentType = response.headers.get('content-type') || '';
+            // Handle 5xx with backoff, for idempotent methods only. Unlike 429, a 5xx
+            // from a proxy or a draining load balancer says nothing about whether the
+            // backend already committed the write — retrying a POST there duplicates
+            // the message.
             let data;
-            if (response.status === 204 || response.headers.get('content-length') === '0') {
-                data = null;
-            }
-            else if (opts.isBinary && response.ok) {
-                // Тело файла нельзя читать как текст: любой байт вне UTF-8 портится
-                // при декодировании, и сохранённый файл оказывается битым.
-                data = Buffer.from(await response.arrayBuffer());
-            }
-            else if (contentType.includes('application/json')) {
-                data = await response.json();
-            }
-            else {
-                data = await response.text();
+            let bodyRead = false;
+            if (RETRYABLE_5XX.has(response.status) && idempotent && !noRetry && attempt < MAX_RETRIES) {
+                // A 504 with the code `timeout` is a search the server stopped because
+                // the query is too heavy: the same query would time out again, so it
+                // goes back to the caller at once. A 504 from a proxy has no such code.
+                if (response.status === 504) {
+                    data = await readBody(response, opts.isBinary).catch(() => null);
+                    bodyRead = true;
+                }
+                if (!isQueryTimeout(response.status, data)) {
+                    const baseMs = 1000;
+                    const waitMs = baseMs * Math.pow(2, attempt) + Math.random() * baseMs;
+                    if (clientFlags?.verbose) {
+                        process.stderr.write(`${ansis.dim(`⏳ Server error ${response.status}, retrying in ${Math.round(waitMs)}ms...`)}\n`);
+                    }
+                    await sleep(waitMs);
+                    continue;
+                }
             }
+            if (!bodyRead)
+                data = await readBody(response, opts.isBinary);
             // Handle errors
             if (!response.ok) {
                 s?.stop('');
@@ -231,8 +236,7 @@ export async function request(opts, clientFlags) {
                 });
             }
             lastError = error;
-            // Only retry network errors for idempotent methods (not POST/DELETE)
-            if (!safeMethod || noRetry || attempt >= MAX_RETRIES) {
+            if (!idempotent || noRetry || attempt >= MAX_RETRIES) {
                 break;
             }
         }
@@ -245,6 +249,27 @@ export async function request(opts, clientFlags) {
         message: lastError?.message || 'Failed to connect to server',
     });
 }
+async function readBody(response, isBinary) {
+    const contentType = response.headers.get('content-type') || '';
+    if (response.status === 204 || response.headers.get('content-length') === '0') {
+        return null;
+    }
+    if (isBinary && response.ok) {
+        // Тело файла нельзя читать как текст: любой байт вне UTF-8 портится
+        // при декодировании, и сохранённый файл оказывается битым.
+        return Buffer.from(await response.arrayBuffer());
+    }
+    if (contentType.includes('application/json')) {
+        return response.json();
+    }
+    return response.text();
+}
+function isQueryTimeout(status, body) {
+    return (status === 504 &&
+        isRecord(body) &&
+        Array.isArray(body.errors) &&
+        body.errors.some((error) => isRecord(error) && error.code === 'timeout'));
+}
 // Недостающий скоуп по RFC 6750 приходит в параметре scope заголовка
 // WWW-Authenticate: Bearer error="insufficient_scope", …, scope="profile:read"
 function scopeFromChallenge(header) {

package/dist/commands/api.js

@@ -4,10 +4,10 @@ import { BaseCommand } from '../base-command.js';
 import { outputError } from '../output.js';
 import { buildListRows, detectIntrospectMode, positionals, findEndpoint, renderIntrospect, } from '../api-introspect.js';
 export default class Api extends BaseCommand {
-    static description = 'Произвольный запрос к API. Список и справка: `api ls` (список эндпоинтов), `api <МЕТОД> <путь> --describe` / `--spec` / `--docs`';
+    static description = 'Произвольный запрос к API. Список и справка: `api ls` (список методов), `api <МЕТОД> <путь> --describe` / `--spec` / `--docs`';
     static examples = [
         '<%= config.bin %> api GET /messages --query chat_id=123',
-        '<%= config.bin %> api POST /messages -F message[chat_id]=12345 -f message[content]="Привет"',
+        "<%= config.bin %> api POST /messages -F 'message[entity_id]=12345' -f 'message[content]=Привет'",
         '<%= config.bin %> api POST /messages --input payload.json',
         `<%= config.bin %> api POST /messages --data '{"message":{"entity_id":123,"content":"Привет"}}'`,
         '<%= config.bin %> api GET /profile -o yaml',
@@ -160,7 +160,7 @@ export default class Api extends BaseCommand {
         const { outputData } = await import('../output.js');
         outputData(data, { ...this.getOutputOptions(), format: outFormat });
     }
-    /** Load the build-time endpoint index (mirrors guide.ts workflows.json loading). */
+    /** Load the build-time endpoint index. */
     async loadEndpoints() {
         try {
             const data = await import('../data/endpoints.json', { with: { type: 'json' } });
@@ -195,7 +195,7 @@ export default class Api extends BaseCommand {
         const entry = findEndpoint(entries, method, path);
         if (!entry) {
             outputError({
-                error: `Эндпоинт не найден: ${method.toUpperCase()} ${path}. Список: pachca api ls`,
+                error: `Метод не найден: ${method.toUpperCase()} ${path}. Список: pachca api ls`,
                 type: 'PACHCA_NOT_FOUND_ERROR',
                 code: null,
             }, errFormat);