feat(cli): CLI improvements — CLI_IMPROVEMENTS_PLAN (C1, C6–C9, D1–D6)

apps/docs/components/api/markdown-content.tsx

@@ -33,6 +33,7 @@ import { Tree, TreeFolder, TreeFile } from '@/components/mdx/tree';
 import { ImageCard } from '@/components/mdx/image-card';
 import { AgentSkillsWorkflows } from '@/components/mdx/agent-skills-workflows';
 import { CliCommands } from '@/components/mdx/cli-commands';
+import { GlobalFlags } from '@/components/mdx/global-flags';
 import { SdkCommands } from '@/components/mdx/sdk-commands';
 import { NpmBadge } from '@/components/mdx/npm-badge';
 import { PackageBadge } from '@/components/mdx/package-badge';
@@ -231,6 +232,7 @@ const components = {
   ScopeRoles,
   AgentSkillsWorkflows,
   CliCommands,
+  GlobalFlags,
   SdkCommands,
   NpmBadge,
   PackageBadge,

apps/docs/components/mdx/cards.tsx

@@ -109,7 +109,7 @@ const iconMap: Record<string, LucideIcon> = {
 const GUIDE_ICONS: Record<string, string> = {
   '/guides/quickstart': 'Zap',
   '/guides/ai-agents': 'Sparkles',
-  '/guides/cli': 'Terminal',
+  '/guides/cli/overview': 'Terminal',
   '/guides/workflows': 'Route',
   '/guides/webhook': 'Webhook',
   '/guides/export': 'Download',

apps/docs/components/mdx/cli-commands.tsx

@@ -1,18 +1,59 @@
-import { generateNavigation } from '@/lib/navigation';
 import { parseOpenAPI } from '@/lib/openapi/parser';
 import { generateUrlFromOperation } from '@/lib/openapi/mapper';
+import { getCliSections, type CliCommand } from '@/lib/cli-data';
 import { CopyableInlineCode } from '@/components/api/copyable-inline-code';
 import { EndpointLink } from '@/components/api/endpoint-link';
 import type { EndpointRequirements } from '@/lib/openapi/types';
 
+function commandHref(command: string): string {
+  // "pachca messages create" → "/api/messages/create"
+  return '/api/' + command.replace(/^pachca\s+/, '').replace(/\s+/g, '/');
+}
+
+function FlagsArgs({ cmd }: { cmd: CliCommand }) {
+  const rows = [
+    ...(cmd.args ?? []).map((a) => ({
+      token: `<${a.name}>`,
+      type: 'аргумент',
+      required: a.required,
+      description: a.description,
+    })),
+    ...cmd.flags.map((f) => ({
+      token: `--${f.name}`,
+      type: f.options ? f.options.join(' | ') : f.type === 'boolean' ? 'boolean' : 'string',
+      required: f.required,
+      description: f.description,
+    })),
+  ];
+  if (rows.length === 0) return null;
+  return (
+    <table className="w-full table-fixed border-none text-[13px] mt-2 mb-1">
+      <colgroup>
+        <col className="w-[26%]" />
+        <col className="w-[26%]" />
+        <col className="w-[48%]" />
+      </colgroup>
+      <tbody className="divide-y divide-glass-divider">
+        {rows.map((r) => (
+          <tr key={r.token}>
+            <td className="py-2 pl-0! pr-3 align-top break-words text-text-primary">
+              <CopyableInlineCode>{r.token}</CopyableInlineCode>
+              {r.required ? <span className="text-danger ml-1">*</span> : null}
+            </td>
+            <td className="py-2 pr-3 align-top break-words text-text-secondary">{r.type}</td>
+            <td className="py-2 pl-0! align-top break-words text-text-secondary">
+              {r.description}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
 export async function CliCommands() {
-  const [sections, api] = await Promise.all([generateNavigation(), parseOpenAPI()]);
-  const methodsSection = sections.find((s) => s.title === 'Методы API');
-  const allCommands = methodsSection
-    ? methodsSection.items.flatMap((group) => group.children ?? [])
-    : [];
+  const [sections, api] = await Promise.all([Promise.resolve(getCliSections()), parseOpenAPI()]);
 
-  // Build a map from URL to requirements for tooltip data
   const requirementsMap = new Map<string, EndpointRequirements>();
   for (const ep of api.endpoints) {
     if (ep.requirements) {
@@ -21,44 +62,42 @@ export async function CliCommands() {
   }
 
   return (
-    <div className="my-6 overflow-x-auto not-prose">
-      <table className="w-full border-none text-[14px]">
-        <thead className="border-b border-glass-border">
-          <tr>
-            <th className="text-left py-4 pl-0! text-text-primary! font-semibold! text-[15px]! normal-case! tracking-normal! bg-transparent!">
-              Команда
-            </th>
-            <th className="text-left py-4 pl-0! text-text-primary! font-semibold! text-[15px]! normal-case! tracking-normal! bg-transparent!">
-              Метод API
-            </th>
-          </tr>
-        </thead>
-        <tbody className="divide-y divide-glass-divider">
-          {allCommands.map((item) => {
-            const command = `pachca ${item.href.replace(/^\/api\//, '').replace(/\//g, ' ')}`;
-            const req = requirementsMap.get(item.href);
-            return (
-              <tr key={item.href}>
-                <td className="py-5 pl-0! text-text-primary">
-                  <CopyableInlineCode>{command}</CopyableInlineCode>
-                </td>
-                <td className="py-5 pl-0! text-text-primary">
-                  <EndpointLink
-                    method={item.method}
-                    href={item.href}
-                    scope={req?.scope}
-                    scopeRoles={req?.scopeRoles?.join(',')}
-                    plan={req?.plan}
-                    noAuth={req?.auth === false}
-                  >
-                    {item.title}
-                  </EndpointLink>
-                </td>
-              </tr>
-            );
-          })}
-        </tbody>
-      </table>
+    <div className="my-6 not-prose">
+      {sections.map((section) => (
+        <section key={section.section} className="mb-10">
+          <h3 className="text-[15px] font-semibold text-text-primary mb-3 font-mono">
+            {section.section}
+          </h3>
+          <div className="space-y-5">
+            {section.commands.map((cmd) => {
+              const href = commandHref(cmd.command);
+              const req = requirementsMap.get(href);
+              return (
+                <div key={cmd.command}>
+                  <div className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
+                    <CopyableInlineCode>{cmd.command}</CopyableInlineCode>
+                    {cmd.method ? (
+                      <EndpointLink
+                        method={cmd.method}
+                        href={href}
+                        scope={req?.scope}
+                        scopeRoles={req?.scopeRoles?.join(',')}
+                        plan={req?.plan}
+                        noAuth={req?.auth === false}
+                      >
+                        {cmd.summary}
+                      </EndpointLink>
+                    ) : (
+                      <span className="text-text-secondary text-[14px]">{cmd.summary}</span>
+                    )}
+                  </div>
+                  <FlagsArgs cmd={cmd} />
+                </div>
+              );
+            })}
+          </div>
+        </section>
+      ))}
     </div>
   );
 }

apps/docs/components/mdx/global-flags.tsx

@@ -0,0 +1,46 @@
+import { getGlobalFlags } from '@/lib/cli-data';
+import { CopyableInlineCode } from '@/components/api/copyable-inline-code';
+
+/**
+ * Global CLI flags table — single source of truth: packages/cli
+ * src/data/global-flags.json (generated from BaseCommand.baseFlags).
+ * Replaces hardcoded RU flag tables in the guide and README.
+ */
+export function GlobalFlags() {
+  const flags = getGlobalFlags();
+
+  return (
+    <div className="my-6 overflow-x-auto not-prose">
+      <table className="w-full border-none text-[14px]">
+        <thead className="border-b border-glass-border">
+          <tr>
+            <th className="text-left py-4 pl-0! text-text-primary! font-semibold! text-[15px]! normal-case! tracking-normal! bg-transparent!">
+              Флаг
+            </th>
+            <th className="text-left py-4 pl-0! text-text-primary! font-semibold! text-[15px]! normal-case! tracking-normal! bg-transparent!">
+              Короткий
+            </th>
+            <th className="text-left py-4 pl-0! text-text-primary! font-semibold! text-[15px]! normal-case! tracking-normal! bg-transparent!">
+              Описание
+            </th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-glass-divider">
+          {flags.map((f) => (
+            <tr key={f.name}>
+              <td className="py-4 pl-0! text-text-primary">
+                <CopyableInlineCode>
+                  {f.type === 'boolean' ? `--${f.name}` : `--${f.name} <value>`}
+                </CopyableInlineCode>
+              </td>
+              <td className="py-4 pl-0! text-text-secondary">
+                {f.char ? <CopyableInlineCode>{`-${f.char}`}</CopyableInlineCode> : null}
+              </td>
+              <td className="py-4 pl-0! text-text-primary">{f.description}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

apps/docs/components/mdx/mdx-components.tsx

@@ -16,6 +16,7 @@ import { Tree, TreeFolder, TreeFile } from '@/components/mdx/tree';
 import { ImageCard } from '@/components/mdx/image-card';
 import { AgentSkillsWorkflows } from '@/components/mdx/agent-skills-workflows';
 import { CliCommands } from '@/components/mdx/cli-commands';
+import { GlobalFlags } from '@/components/mdx/global-flags';
 import { SdkCommands } from '@/components/mdx/sdk-commands';
 import { NpmBadge } from '@/components/mdx/npm-badge';
 import { PackageBadge } from '@/components/mdx/package-badge';
@@ -527,6 +528,7 @@ export const customMdxComponents = {
   FormPlayground,
   AgentSkillsWorkflows,
   CliCommands,
+  GlobalFlags,
   SdkCommands,
   NpmBadge,
   PackageBadge,

apps/docs/content/guides/ai-agents.mdx

@@ -123,28 +123,33 @@ description: "Как Пачка работает с AI-агентами: тре
 
 ### CLI
 
-Самый быстрый и производительный способ. Минимальное влияние на контекст агента — не нужно загружать документацию, агент узнаёт возможности через `--help`. Если есть доступ к shell, агент может генерировать скрипты для типовых задач.
+Самый быстрый и производительный способ. Агент работает теми же **типизированными командами**, что и человек: каждый метод API — отдельная команда с флагами и валидацией. Готовые последовательности под типовые задачи — в [Сценариях](/guides/cli/workflows).
 
 ```bash
-# Установка
-npm install -g @pachca/cli
-
-# Агент может вызывать любые команды
-pachca messages create --entity-id 123 --content "Готово"
-pachca users list -o json
+# Без установки — агент запускает сразу, всегда последняя версия
+npx @pachca/cli messages create --entity-id 123 --content "Готово" --no-input -o json
+npx @pachca/cli users list --no-input -o json
 ```
 
-<Info>CLI автоматически определяет неинтерактивную среду (stdin/stdout — не TTY) и адаптируется: выводит JSON вместо таблиц, отключает промпты и спиннер, а при пропущенных обязательных флагах — возвращает ошибку вместо запроса ввода. Агенту не нужна дополнительная настройка — достаточно передать все обязательные флаги.</Info>
+Токен агент передаёт через переменную окружения `PACHCA_TOKEN` (или флаг `--token` для разового вызова) — ничего не пишется на диск, токен берётся из секретов агента и **не коммитится в репозиторий**.
+
+Для ветвления логики агент использует exit codes (`0` успех, `3` нет доступа, `4` не найдено) и поле `type` в JSON-ошибке (`PACHCA_AUTH_ERROR`, `PACHCA_VALIDATION_ERROR` и т.д.).
+
+Если нужного метода нет под рукой, не обязательно грузить документацию в контекст или открывать сайт — CLI подскажет точечно: `api ls` (список эндпоинтов), затем `api <МЕТОД> <путь> --describe` (параметры, тело, эквивалентная команда), и агент сразу её вызывает.
+
+<Info>CLI автоматически определяет неинтерактивную среду (stdin/stdout — не TTY) и адаптируется: выводит JSON вместо таблиц, отключает промпты и спиннер, а при пропущенных обязательных флагах — возвращает ошибку вместо запроса ввода. Флаг `--no-input -o json` фиксирует этот режим явно.</Info>
 
 <CardGroup columns={2}>
   <Card title="@pachca/cli" href="https://www.npmjs.com/package/@pachca/cli">
     Пакет на npm
   </Card>
-  <Card title="Руководство CLI" href="/guides/cli">
-    Полная документация по CLI — команды, флаги, пайпы, сценарии
+  <Card title="Руководство CLI" href="/guides/cli/overview">
+    Установка, авторизация, скрипты и CI, полный справочник команд
   </Card>
 </CardGroup>
 
+Команда `pachca api` (прямые запросы) и встроенный справочник по API (`api ls` / `--describe` / `--spec` / `--docs`) — в разделе [Прямые запросы](/guides/cli/api-requests).
+
 ### Context7 MCP
 
 Самый надёжный вариант для постоянной работы с API. [Context7](https://context7.com) — MCP-сервер, который отдаёт актуальную документацию прямо в контекст агента. Подходит для удалённых интеграций с OAuth, многошаговых сценариев и когда вы часто просите агента выполнять разные задачи в Пачке из промптов.