@pachca/cli 2026.11.0 → 2026.11.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026.11.2  (10 ноября 2026)
+
+- **Добавлено** (bots listen-events): События бота в реальном времени без публичного адреса: JSONL в терминале или пересылка на локальный обработчик, как исходящий вебхук, с подписью, свежим `webhook_timestamp` и ответом на отправку формы. Запись удаляется из истории после ответа 2xx.
+- **Изменено**: Для запуска CLI требуется Node.js 20.3.0 или новее
+
+## 2026.11.1  (9 ноября 2026)
+
+- **Изменено** (auth status): Показывает токен, с которым работают команды, в том числе из `--token` и `PACHCA_TOKEN`. Владельца, права и срок жизни такого токена команда спрашивает у сервера и называет сохранённый профиль, который не используется, пока задан `PACHCA_TOKEN`.
+- **Изменено**: Подсказки к отказу `insufficient_scope` ведут к `pachca auth status` с тем же `--token` или `--profile`, что у команды, а для сохранённого профиля в `-o json` ещё и с `--remote`
+- **Изменено** (auth login): Подсказка `pachca auth status` после входа называет профиль, если без него команда покажет другой токен, а при заданном `PACHCA_TOKEN` вход предупреждает, что команды используют переменную
+- **Добавлено** (messages get, messages list, messages create, messages update, search list-messages): В ответах с сообщениями есть поля `source` и `application`: через что сотрудник отправил сообщение и какая программа
+- **Изменено** (chats list, messages list): `--order` без `--sort` задаёт направление по `id`
+- **Изменено** (bots create, bots update, bots update-webhook): В описании адреса вебхука коды отказа, а в описании шаблона проверка синтаксиса
+- **Изменено** (users update): В описании чата для перевода в гости письмо о смене роли
+
 ## 2026.11.0  (4 ноября 2026)
 
 - **Изменено** (tasks create): Работает без `--kind` и не спрашивает тип в терминале: по умолчанию создаётся простое напоминание

package/README.md

@@ -4,6 +4,8 @@
 
 ## Установка
 
+Требуется Node.js 20.3.0 или новее.
+
 ```
 npm install -g @pachca/cli
 
@@ -292,6 +294,24 @@ cat data.csv | pachca upload - --name data.csv
 
 Команда `upload` автоматически получает подпись (`POST /uploads`) и загружает файл на S3. Возвращает `key` — используйте его в `--files` при создании сообщений. Расширение `name` в файле сообщения должно совпадать с расширением имени в `key`.
 
+## События бота
+
+```bash
+PACHCA_TOKEN=$PACHCA_BOT_TOKEN pachca bots listen-events
+PACHCA_TOKEN=$PACHCA_BOT_TOKEN PACHCA_SIGNING_SECRET=$PACHCA_SIGNING_SECRET \
+  pachca bots listen-events --forward-to http://localhost:3000/webhook
+```
+
+Нужен токен бота с правом `webhooks:events:read` и включённая настройка «Сохранять историю событий». Команда подключается к потоку событий, дожидается подтверждения подписки, дочитывает историю от старых событий к новым и меняет ссылку до истечения срока.
+
+Без `--forward-to` каждая запись истории (`id`, `event_type`, `payload`, `created_at`) выводится строкой JSONL и остаётся в истории. При запуске печатается вся накопленная история, после переподключения только новые записи.
+
+С `--forward-to` команда отправляет `payload` запросом POST, как исходящий вебхук, и удаляет запись из истории после ответа 2xx. Для этого нужно право `webhooks:events:delete`. Если задан `PACHCA_SIGNING_SECRET`, тело подписано заголовком `Pachca-Signature`. В `webhook_timestamp` стоит время пересылки, а в `Idempotency-Key` приходит `id` записи. Ответ обработчика на отправку формы (2xx, либо 400 или 422 с `errors`) команда передаёт в Пачку, для этого нужно право `views:write`. Пачка принимает ответ на форму в течение 5 секунд с отправки. Отправку формы старше 10 секунд команда обработчику не пересылает и удаляет из истории: сотрудник к этому времени уже видел ошибку и мог отправить форму снова. Другой ответ, ошибка или таймаут останавливают команду, а запись остаётся в истории. Редиректы не выполняются. Запись, которую обработчик не может принять, удалите тем же токеном бота командой `PACHCA_TOKEN=$PACHCA_BOT_TOKEN pachca bots remove-event <id> --force`: `id` есть в сообщении об ошибке.
+
+`--forward-to` рассчитан на бота без адреса вебхука. Запускайте для бота одну такую команду: история у слушателей общая.
+
+`--timeout` задаёт таймаут запросов к API и к обработчику и ожидания подтверждения подписки в секундах (по умолчанию `defaults.timeout`, `PACHCA_TIMEOUT` или 30). `--no-retry` отключает переподключение, а отдельные запросы к API по-прежнему повторяются при 429 и 5xx. `--verbose` не печатает HTTP-диагностику этой команды, чтобы подписанная ссылка не попала в логи. Ctrl+C завершает команду.
+
 ## Пагинация
 
 ```

package/README.template.md

@@ -4,6 +4,8 @@
 
 ## Установка
 
+Требуется Node.js 20.3.0 или новее.
+
 ```
 npm install -g @pachca/cli
 
@@ -74,6 +76,24 @@ cat data.csv | pachca upload - --name data.csv
 
 Команда `upload` автоматически получает подпись (`POST /uploads`) и загружает файл на S3. Возвращает `key` — используйте его в `--files` при создании сообщений. Расширение `name` в файле сообщения должно совпадать с расширением имени в `key`.
 
+## События бота
+
+```bash
+PACHCA_TOKEN=$PACHCA_BOT_TOKEN pachca bots listen-events
+PACHCA_TOKEN=$PACHCA_BOT_TOKEN PACHCA_SIGNING_SECRET=$PACHCA_SIGNING_SECRET \
+  pachca bots listen-events --forward-to http://localhost:3000/webhook
+```
+
+Нужен токен бота с правом `webhooks:events:read` и включённая настройка «Сохранять историю событий». Команда подключается к потоку событий, дожидается подтверждения подписки, дочитывает историю от старых событий к новым и меняет ссылку до истечения срока.
+
+Без `--forward-to` каждая запись истории (`id`, `event_type`, `payload`, `created_at`) выводится строкой JSONL и остаётся в истории. При запуске печатается вся накопленная история, после переподключения только новые записи.
+
+С `--forward-to` команда отправляет `payload` запросом POST, как исходящий вебхук, и удаляет запись из истории после ответа 2xx. Для этого нужно право `webhooks:events:delete`. Если задан `PACHCA_SIGNING_SECRET`, тело подписано заголовком `Pachca-Signature`. В `webhook_timestamp` стоит время пересылки, а в `Idempotency-Key` приходит `id` записи. Ответ обработчика на отправку формы (2xx, либо 400 или 422 с `errors`) команда передаёт в Пачку, для этого нужно право `views:write`. Пачка принимает ответ на форму в течение 5 секунд с отправки. Отправку формы старше 10 секунд команда обработчику не пересылает и удаляет из истории: сотрудник к этому времени уже видел ошибку и мог отправить форму снова. Другой ответ, ошибка или таймаут останавливают команду, а запись остаётся в истории. Редиректы не выполняются. Запись, которую обработчик не может принять, удалите тем же токеном бота командой `PACHCA_TOKEN=$PACHCA_BOT_TOKEN pachca bots remove-event <id> --force`: `id` есть в сообщении об ошибке.
+
+`--forward-to` рассчитан на бота без адреса вебхука. Запускайте для бота одну такую команду: история у слушателей общая.
+
+`--timeout` задаёт таймаут запросов к API и к обработчику и ожидания подтверждения подписки в секундах (по умолчанию `defaults.timeout`, `PACHCA_TIMEOUT` или 30). `--no-retry` отключает переподключение, а отдельные запросы к API по-прежнему повторяются при 429 и 5xx. `--verbose` не печатает HTTP-диагностику этой команды, чтобы подписанная ссылка не попала в логи. Ctrl+C завершает команду.
+
 ## Пагинация
 
 ```

package/dist/base-command.js

@@ -1,5 +1,5 @@
 import { Command, Flags } from '@oclif/core';
-import { resolveToken, TokenNotFoundError, ProfileNotFoundError, getAuthMethod, getDefaults, profileFlag, } from './profiles.js';
+import { resolveToken, TokenNotFoundError, ProfileNotFoundError, getAuthMethod, getDefaults, profileFlag, tokenSource, } from './profiles.js';
 import { ApiError, getExitCode, formatDryRun, request } from './client.js';
 import { outputData, outputError, outputSuccess } from './output.js';
 import { defaultOutputFormat, isInteractive } from './utils.js';
@@ -246,16 +246,38 @@ export class BaseCommand extends Command {
     reportScopeError(err) {
         const format = this.getOutputFormat();
         const scope = typeof err.details.scope === 'string' ? err.details.scope : undefined;
-        if (format === 'json' || !process.stderr.isTTY) {
-            outputError(err.details, format);
+        // `auth status` checks the token every command uses. A bare run reads the active
+        // profile; a token or profile named on this command, by a flag or by a variable that
+        // may have been set for this one command, has to be named again. The token value is
+        // never echoed back.
+        const source = tokenSource({ token: this.parsedFlags.token, profile: this.parsedFlags.profile });
+        const human = format !== 'json' && process.stderr.isTTY;
+        const again = source.kind === 'flag'
+            ? human ? ' --token <токен>' : ' --token <token>'
+            : source.kind === 'profile' && source.via !== 'active_profile'
+                ? ` --profile ${source.profileName}`
+                : '';
+        // A token from the environment may have been set for this one command
+        // (`PACHCA_TOKEN=… pachca …`): a bare `auth status` would then read another one.
+        const check = source.kind === 'env'
+            ? `PACHCA_TOKEN=${human ? '<токен>' : '<token>'} pachca auth status`
+            : 'pachca auth status';
+        if (!human) {
+            // A saved profile keeps the scope list from login, which may still name the
+            // scope just refused: only the server's answer settles it.
+            const remote = source.kind === 'profile' ? ' --remote' : '';
+            outputError({ ...err.details, hint: `${check}${remote}${again}` }, format);
             this.exit(3);
         }
         const resolved = this.tryResolveProfile();
         const profile = resolved?.profile;
         process.stderr.write(`✗ Не хватает права${scope ? ` ${scope}` : ''}.\n`);
+        // A command's own check before any request (no HTTP status) says why it needs the right.
+        if (err.details.code === null)
+            process.stderr.write(`  ${err.details.error}.\n`);
         if (!profile) {
             process.stderr.write(`  У токена ${scope ? 'этого' : 'нужного'} права нет.\n`);
-            process.stderr.write(`  Проверить права токена: pachca oauth token-info -o json\n`);
+            process.stderr.write(`  Проверить токен и его права: ${check}${again}\n`);
             this.exit(3);
         }
         // The scope list in the profile is a copy taken at login. When it still names
@@ -265,7 +287,7 @@ export class BaseCommand extends Command {
         const listedLocally = !!scope && !!profile.scopes?.includes(scope);
         if (listedLocally) {
             process.stderr.write(`  В сохранённом списке право есть, но у токена его уже нет: список устарел.\n`);
-            process.stderr.write(`  Обновить список: pachca auth status --remote${flag}\n`);
+            process.stderr.write(`  Обновить список: pachca auth status --remote${again}\n`);
         }
         else {
             process.stderr.write(`  У токена ${scope ? 'этого' : 'нужного'} права нет.\n`);

package/dist/client.js

@@ -98,14 +98,20 @@ function parseRetryAfter(header) {
         return null;
     return Math.max(ms, 0);
 }
-export async function request(opts, clientFlags) {
-    const url = buildUrl(opts.path, opts.query);
+/**
+ * Seconds to wait: the value asked for (a flag or `defaults.timeout`), else PACHCA_TIMEOUT, else 30.
+ * A value that is not a positive number means 30: a timeout of 0 would abort on the next tick,
+ * which is never what anyone means by `--timeout 0`. Timers take at most 2^31 - 1 ms.
+ */
+export function resolveTimeoutSeconds(requested) {
     const rawEnvTimeout = process.env.PACHCA_TIMEOUT ? Number(process.env.PACHCA_TIMEOUT) : undefined;
     const envTimeout = rawEnvTimeout && !Number.isNaN(rawEnvTimeout) ? rawEnvTimeout : undefined;
-    const requestedTimeout = opts.timeout ?? clientFlags?.timeout ?? envTimeout ?? DEFAULT_TIMEOUT;
-    // A non-positive timeout aborts on the next tick, which is never what anyone
-    // means by `--timeout 0`. The env var already ignored 0; make the flag agree.
-    const timeoutSeconds = requestedTimeout > 0 ? requestedTimeout : DEFAULT_TIMEOUT;
+    const value = Number(requested ?? envTimeout ?? DEFAULT_TIMEOUT);
+    return Number.isFinite(value) && value > 0 ? Math.min(value, 2_147_483) : DEFAULT_TIMEOUT;
+}
+export async function request(opts, clientFlags) {
+    const url = buildUrl(opts.path, opts.query);
+    const timeoutSeconds = resolveTimeoutSeconds(opts.timeout ?? clientFlags?.timeout);
     const noRetry = opts.noRetry ?? clientFlags?.['no-retry'] ?? false;
     const method = opts.method.toUpperCase();
     // The same set is retried after a 5xx and after a network error. A repeated

package/dist/commands/auth/login.js

@@ -1,9 +1,10 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
-import { setProfile, setActiveProfile, getActiveProfile, getProfile, getSecretStorage, expiresAtFromNow, } from '../../profiles.js';
+import { setProfile, setActiveProfile, getActiveProfile, getProfile, getSecretStorage, expiresAtFromNow, tokenSource, } from '../../profiles.js';
 import { isSecretStoreAvailable } from '../../secret-store.js';
 import { ApiError, request } from '../../client.js';
 import { outputError } from '../../output.js';
+import { fetchIdentity } from '../../identity.js';
 import { OAuthError, copyToClipboard, deviceName, openBrowser, pollForToken, requestDeviceCode, } from '../../oauth.js';
 export default class AuthLogin extends BaseCommand {
     static description = 'Вход в аккаунт и сохранение профиля';
@@ -68,7 +69,7 @@ export default class AuthLogin extends BaseCommand {
             ? { access_token: flags.token }
             : await this.deviceLogin(profileName, !flags['no-browser'], flags.quiet);
         const tokenInfo = await this.verifyToken(grant.access_token);
-        const identity = await this.fetchIdentity(grant.access_token, tokenInfo.user_id);
+        const identity = await fetchIdentity(grant.access_token, tokenInfo.user_id);
         const scopes = grant.scope ? grant.scope.split(' ').filter(Boolean) : tokenInfo.scopes;
         const profile = {
             type: identity.isBot ? 'bot' : 'user',
@@ -197,22 +198,6 @@ export default class AuthLogin extends BaseCommand {
             throw error;
         }
     }
-    async fetchIdentity(token, userId) {
-        try {
-            const response = await request({ method: 'GET', path: '/profile', token }, { quiet: true });
-            const data = response.data.data;
-            const name = `${data.first_name || ''} ${data.last_name || ''}`.trim();
-            return {
-                name: name || `User #${userId}`,
-                email: data.email || null,
-                isBot: data.bot || false,
-            };
-        }
-        catch {
-            // profile:read scope not available — user_id from token info is enough
-            return { name: `User #${userId}`, email: null, isBot: false };
-        }
-    }
     report(profileName, profile, scopes) {
         const format = this.getOutputFormat();
         if (format === 'json') {
@@ -243,7 +228,14 @@ export default class AuthLogin extends BaseCommand {
         else {
             process.stderr.write(`  Токен в файле конфигурации (хранилище ключей недоступно)\n`);
         }
-        process.stderr.write(`  Состояние входа: pachca auth status\n`);
+        // A bare `auth status` shows the token other commands would use: PACHCA_TOKEN
+        // when it is set, or the active profile, which need not be the one just saved.
+        const src = tokenSource({});
+        const statusFlag = src.kind === 'profile' && src.profileName === profileName ? '' : ` --profile ${profileName}`;
+        process.stderr.write(`  Состояние входа: pachca auth status${statusFlag}\n`);
+        if (src.kind === 'env') {
+            process.stderr.write(`  Пока задан PACHCA_TOKEN, команды используют его, а не профиль ${profileName}\n`);
+        }
     }
 }
 /** Read a token piped into the command, so it never appears in the shell history. */

package/dist/commands/auth/status.js

@@ -1,8 +1,9 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../base-command.js';
-import { getActiveProfile, getAuthMethod, getProfile, getSecretStorage, updateProfileScopes, } from '../../profiles.js';
-import { request } from '../../client.js';
+import { getActiveProfile, getAuthMethod, getProfile, getSecretStorage, listProfiles, tokenSource, updateProfileScopes, } from '../../profiles.js';
+import { ApiError, request } from '../../client.js';
 import { outputError } from '../../output.js';
+import { fetchIdentity } from '../../identity.js';
 /** Human-readable time left, or null when the token has no expiry at all. */
 function describeExpiry(profile) {
     if (getAuthMethod(profile) === 'token')
@@ -18,10 +19,11 @@ function describeExpiry(profile) {
     return minutes < 60 ? `осталось ${minutes} мин` : `осталось ${Math.round(minutes / 60)} ч`;
 }
 export default class AuthStatus extends BaseCommand {
-    static description = 'Статус текущего профиля';
+    static description = 'Чей токен используют команды и какие у него права';
     static examples = [
         '<%= config.bin %> auth status',
         '<%= config.bin %> auth status -o json',
+        'PACHCA_TOKEN=$TOKEN <%= config.bin %> auth status -o json',
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -33,12 +35,30 @@ export default class AuthStatus extends BaseCommand {
     async run() {
         const { flags } = await this.parse(AuthStatus);
         this.parsedFlags = flags;
-        const profileName = flags.profile || process.env.PACHCA_PROFILE || getActiveProfile();
         const format = this.getOutputFormat();
-        if (!profileName) {
-            outputError({ error: 'No active profile. Run: pachca auth login', type: 'PACHCA_USAGE_ERROR', code: null }, format);
+        // The token every other command would use, picked in the same order:
+        // --token, --profile, PACHCA_TOKEN, PACHCA_PROFILE, the active profile.
+        // Agents and CI usually pass PACHCA_TOKEN with no profile at all, and this
+        // is the command they are sent to check the connection.
+        const source = tokenSource({ token: flags.token, profile: flags.profile });
+        if (source.kind === 'flag') {
+            await this.showPassedToken(flags.token, '--token');
+            return;
+        }
+        if (source.kind === 'env') {
+            await this.showPassedToken(process.env.PACHCA_TOKEN, 'PACHCA_TOKEN');
+            return;
+        }
+        if (source.kind === 'none') {
+            outputError({
+                error: 'No active profile. Run: pachca auth login',
+                type: 'PACHCA_USAGE_ERROR',
+                code: null,
+                hint: 'pachca auth login, or set PACHCA_TOKEN',
+            }, format);
             this.exit(2);
         }
+        const profileName = source.kind === 'profile' ? source.profileName : undefined;
         const profile = getProfile(profileName);
         if (!profile) {
             outputError({ error: `Profile "${profileName}" not found`, type: 'PACHCA_USAGE_ERROR', code: null }, format);
@@ -67,6 +87,7 @@ export default class AuthStatus extends BaseCommand {
         if (format === 'json') {
             this.output({
                 profile: profileName,
+                source: source.kind === 'profile' ? source.via : null,
                 type: profile.type,
                 user: profile.user,
                 email: profile.email || null,
@@ -111,10 +132,88 @@ export default class AuthStatus extends BaseCommand {
             process.stderr.write(`  Список прав в профиле расходился с сервером и был обновлён\n`);
         }
     }
+    /**
+     * A token passed to the command rather than saved in a profile. Nothing about it
+     * is stored, so everything comes from the server: whose it is and what it carries.
+     * A revoked token or no network ends the command with the usual error and hint.
+     */
+    async showPassedToken(token, label) {
+        // A PACHCA_TOKEN left in the environment silently wins over the profile the
+        // person thinks they are using. Name that profile, so the mix-up is visible,
+        // also when the forgotten token no longer works.
+        const profileName = label === 'PACHCA_TOKEN' ? process.env.PACHCA_PROFILE || getActiveProfile() : undefined;
+        const unusedProfile = profileName && listProfiles()[profileName] ? profileName : null;
+        const clientFlags = { ...this.getClientFlags(), quiet: true };
+        let info;
+        try {
+            const response = await request({ method: 'GET', path: '/oauth/token/info', token }, clientFlags);
+            info = response.data.data;
+        }
+        catch (error) {
+            // A dead token (401) or one whose owner lost access (403 access_denied):
+            // the profile it hides may still work, so say so.
+            const dead = error instanceof ApiError &&
+                (error.details.code === 401 || (error.details.code === 403 && error.details.validation_code === 'access_denied'));
+            if (dead && unusedProfile) {
+                const human = this.getOutputFormat() !== 'json' && process.stderr.isTTY;
+                error.details.unused_profile = unusedProfile;
+                error.details.hint = human
+                    ? `Профиль ${unusedProfile} не используется, пока задан PACHCA_TOKEN: уберите переменную или добавьте --profile ${unusedProfile}`
+                    : `unset PACHCA_TOKEN, or add --profile ${unusedProfile}`;
+            }
+            throw error;
+        }
+        const identity = await fetchIdentity(token, info.user_id, clientFlags);
+        const type = identity.isBot === null ? null : identity.isBot ? 'bot' : 'user';
+        const user = identity.isBot ? `${identity.name} (бот)` : identity.name;
+        const scopes = info.scopes ?? [];
+        // A CLI login or an app's token lives an hour from issue, and nothing renews a
+        // token passed to the command. Other tokens have no lifetime at all.
+        const expiresIn = info.expires_in ?? null;
+        const issuedAt = info.created_at ? Date.parse(info.created_at) : Number.NaN;
+        const expiresAt = expiresIn && !Number.isNaN(issuedAt) ? new Date(issuedAt + expiresIn * 1000) : null;
+        if (this.getOutputFormat() === 'json') {
+            this.output({
+                profile: null,
+                source: label,
+                type,
+                user,
+                user_id: info.user_id,
+                email: identity.email,
+                auth: 'token',
+                expires_at: expiresAt ? expiresAt.toISOString() : null,
+                expires_in: expiresIn,
+                scopes,
+                scopes_source: 'server',
+                storage: null,
+                secret_readable: true,
+                unused_profile: unusedProfile,
+            });
+            return;
+        }
+        const emailStr = identity.email ? ` (${identity.email})` : '';
+        const from = label === '--token' ? 'флага --token' : 'PACHCA_TOKEN';
+        const typeStr = type ?? (identity.noScope ? 'бот или сотрудник: без права profile:read не узнать' : 'бот или сотрудник: профиль не прочитан');
+        process.stderr.write(`  Подключён как: ${user}${emailStr}  [${typeStr}]\n`);
+        if (expiresIn) {
+            const minutesLeft = expiresAt ? Math.round((expiresAt.getTime() - Date.now()) / 60_000) : null;
+            const left = minutesLeft === null ? `живёт ${Math.round(expiresIn / 60)} мин от выдачи` : minutesLeft > 0 ? `осталось ${minutesLeft} мин` : 'истёк';
+            process.stderr.write(`  Вход: токеном из ${from}, ${left}, CLI его не продлевает\n`);
+        }
+        else {
+            process.stderr.write(`  Вход: готовым токеном из ${from}\n`);
+        }
+        process.stderr.write(scopes.length
+            ? `  Права по данным сервера (${scopes.length}): ${scopes.join(', ')}\n`
+            : `  Права по данным сервера: ни одного\n`);
+        if (unusedProfile) {
+            process.stderr.write(`  Профиль ${unusedProfile} не используется, пока задан PACHCA_TOKEN. Чтобы работать с ним, добавьте --profile ${unusedProfile} или уберите переменную.\n`);
+        }
+    }
     /** Ask the server what the token really carries. Null when it cannot be asked. */
     async fetchRemoteScopes(token) {
         try {
-            const response = await request({ method: 'GET', path: '/oauth/token/info', token }, { quiet: true });
+            const response = await request({ method: 'GET', path: '/oauth/token/info', token }, { ...this.getClientFlags(), quiet: true });
             const info = response.data.data;
             return info?.scopes ?? null;
         }

package/dist/commands/bots/create.js

@@ -19,7 +19,7 @@ export default class BotsCreate extends BaseCommand {
             description: "Никнейм бота: латинские буквы, цифры и `_`, в конце `_bot`, свободный в пространстве. Ник не по формату отвечает `400` на поле `bot.nickname` с кодом `invalid`, а занятый ник — с кодом `taken`. Без поля ник собирается из имени в латинской транслитерации с `_bot` в конце, а если такой ник занят, с `_2_bot`, `_3_bot` и далее. (макс. 255 символов)",
         }),
         'outgoing-url': Flags.string({
-            description: "URL исходящего вебхука (макс. 255 символов)",
+            description: "URL исходящего вебхука: публичный адрес с протоколом `http` или `https`. Иначе ответ `400` на поле `webhook.outgoing_url` с кодом `webhook_url_invalid`, `webhook_url_unresolved` или `webhook_url_forbidden`. (макс. 255 символов)",
         }),
         'events': Flags.string({
             description: "События, на которые подписан бот. Без поля бот подписан на `message_new`.",
@@ -34,7 +34,7 @@ export default class BotsCreate extends BaseCommand {
             description: "Скоупы (права доступа) токена бота. Если не указано, бот получает набор по умолчанию. Боту доступны не все скоупы: часть из них разрешена только пользовательским ролям, и попытка назначить такой скоуп возвращает `400`. Служебные значения `bot` и `all` назначать нельзя.",
         }),
         'template': Flags.string({
-            description: "Шаблон форматирования входящего вебхука",
+            description: "Шаблон форматирования входящего вебхука. Шаблон с синтаксической ошибкой у источника `simple`, в том числе у пустого бота с `kind: simple`, даёт ответ `400` на этом поле с кодом `invalid`, и бот не создаётся. Причина приходит в `message`.",
         }),
         'template-engine': Flags.string({
             description: "Шаблонизатор для обработки шаблона входящего вебхука. Без этого поля бот получает `liquid`, а пустой бот (`empty: true`) — `mustache`.",