ARC CLI — Справочник команд

ARC CLI — инструмент командной строки для взаимодействия с Arc Cloud. Управляй проектами, задачами, вики и скилами прямо из терминала.

• Исходный код: clients/arc-cli.ts
• API-клиент: clients/lib/api.ts
• Сборка: scripts/build-arc.sh (скомпилированный binary)

Установка и настройка

Конфигурация хранится в ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

Авторизация через device code flow. Открывает браузер для подтверждения.

arc login                          # сервер за замовчуванням: https://arc-os.co
arc login https://my-server.com    # кастомний сервер

После запуска CLI выведет URL и одноразовый код. Открой URL в браузере, подтверди авторизацию — CLI автоматически получит токен.

arc login --token <token>

Прямая авторизация токеном (для автоматизации или когда device flow недоступен).

arc login --token eyJhbGciOiJIUzI1NiI...

CLI валидирует токен через API перед сохранением.

arc logout

Удаляет credentials из ~/.arc/config.json и убирает ARC-блок из CLAUDE.md (если есть).

arc logout

arc projects

Список доступных проектов на сервере.

arc projects

Вывод:

Available projects:

  Name                   Type           Status
  --------------------------------------------------
  arc-v2                 bot            running
  my-project             bot            unknown

Запуск сессии

arc <project> [mode]

Инициализирует сессию Claude с полным контекстом проекта. Эквивалент arc start <project> [mode].

arc my-project dev             # режим dev (за замовчуванням)
arc my-project prod            # режим prod
arc --role clceo my-project    # з роллю CEO

Что происходит при запуске:

1. Запрос GET /api/cli/init/:project/:mode — получение CLAUDE.md, worker config, skills
2. Session-start picker (issue #115) — интерактивный выбор активной задачи для сессии: open issues (sort P0→P3 + recent-first, fuzzy filter если >10), recently-closed (с reopen-confirm на pick), [n] create new, [q] skip с double-confirm. Selected id сохраняется в ~/.arc/sessions/<project>-<worker>.json как active_issue_id
3. Injection контекста в локальный CLAUDE.md (ARC Cloud block + Active issue: #N — Title block)
4. ARC_ACTIVE_ISSUE_ID=<id> env var передаётся в Claude subprocess — Bash tool видит его для arc issue log без re-prompt
5. Очистка deprecated .mcp.json записей (если есть)
6. Запуск claude subprocess с TTY interactivity
7. Старт background watcher (см. «Мониторинг сессий»)

Параметры:

Non-interactive bypass: ARC_ISSUE_ID=42 arc my-project dev пропускает picker и использует заданный id (для CI/скриптов).

Mid-session switch: arc issue switch <id> (из параллельного терминала) переключает активную задачу — пишет switched_away на предыдущей + switched_in на новой. Текущая сессия подхватит новый id после рестарта.

arc continue <project> [mode]

Resume последней сессии Claude Code (24-часовое окно). Авто-восстанавливает active_issue_id без re-prompt.

arc continue my-project             # підхопити попередню сесію + active issue
arc continue my-project --reselect-issue   # force re-run picker

arc tour

Интерактивный 5-шаговый онбординг в терминале (mirrors web checklist). Прогресс синхронизируется с web дашбордом.

arc tour

Управление задачами (Issues)

arc issues [--status <filter>]

Список задач проекта.

arc issues                    # тільки open (за замовчуванням)
arc issues --status closed    # тільки закриті
arc issues --status all       # всі задачі

Вывод:

3 issue(s):
- #12 [P1] Add dark mode [ux, frontend]
- #15 [P2] Fix login timeout
- #18 [P0] Critical: DB migration

arc issue create --title "..." [options]

Создай новую задачу.

arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"
arc issue create --title "Fix bug" --body "Detailed description here" --priority P0

Параметры:

arc issue update <id> [options]

Обнови существующую задачу.

arc issue update 12 --status closed
arc issue update 15 --priority P0 --title "Critical: Fix login timeout"
arc issue update 18 --body "Updated description with more context"

Параметры:

Нужен хотя бы один параметр для обновления.

arc issue log <id> "<text>" [--author <name>]

Добавить запись прогресса к задаче (activity log).

arc issue log 12 "Started implementation"
arc issue log 12 "Dark mode toggle works" --author "developer"

Параметры:

Backend (POST /api/mcp/issues/:project/:id/log) принимает опциональные поля type (whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) и ts (ISO-8601 для backdated entries, future-dated клампится до now). Используется внутренне session-start picker (#115) и arc retro (#117).

arc issue switch <id>

Переключить активную задачу для текущей сессии (issue #115). Сохраняет в ~/.arc/sessions/<project>-<worker>.json, пишет switched_away на предыдущей задаче + switched_in на новой.

arc issue switch 42
arc issue switch 42 --worker consultant   # для конкретного воркера (default: developer)

Validation: задача должна существовать + быть open. Если закрыта — сначала arc issue update <id> --status open.

arc retro <project> [options]

Реконструировать задачи retroactively из session history + git log (issue #117). Сканирует ~/.arc/sessions/<project>-*.json, читает first user prompt из transcript JSONL, собирает commits через git log --since=started_at --until=ended_at.

arc retro gapap                       # dry-run — друкує план
arc retro gapap --apply               # створює issues
arc retro gapap --since 2026-01-01    # тільки після цієї дати
arc retro gapap --worker consultant   # тільки для одного worker

Что пропускается автоматически:

Что происходит при --apply:

1. createIssue для каждого candidate (priority=P2, label=retro)
2. Backdated activity entries: session_start (started_at) + auto_summary per commit (commit timestamp) + session_end (ended_at) — через POST /log с полем ts
3. Сессии >30 дней с commits → status=closed сразу. Recent unfinished → status=open.

Скилы и знания

arc skill <name>

Загрузить скил из Cloud. Выводит инструкции скила и evals (если есть).

arc skill consultant_system
arc skill crm-api-reference

Нужна переменная ARC_PROJECT (устанавливается автоматически при arc start).

Если скил не найден, CLI выведет список доступных.

arc kb search "<query>"

Поиск по вики проекта. Keyword match по именам файлов, возвращает до 5 лучших результатов (контент обрезается до 2000 символов).

arc kb search "deployment"
arc kb search "arc-cli"

arc learnings

Накопленные правила и корректировки из всех сессий проекта.

arc learnings

Вывод:

- [cli] Always validate project name before API calls
- [deploy] Test nginx config before reload

Вики и Roadmap

arc wiki update --file <name> --content "..."

Создай или обнови страницу вики проекта.

arc wiki update --file "architecture" --content "# Architecture\n\nMain components..."
arc wiki update --file "deploy-guide" --content "$(cat my-doc.md)"

Параметры:

Вывод: Wiki created: architecture.md (342 bytes) или Wiki updated: ...

arc roadmap sync --phase <id> --status <text> [--notes "..."]

Обнови статус фазы в roadmap проекта.

arc roadmap sync --phase 45 --status "IN PROGRESS"
arc roadmap sync --phase 44 --status "DONE" --notes "All analytics redesigned"

Параметры:

Отчётность

arc report --summary "..." [options]

Отправить отчёт сессии в Arc Cloud.

arc report --summary "Implemented dark mode with system preference detection"
arc report --summary "Fixed auth bug" --files "auth.ts,middleware.ts" --decisions "Switched to HMAC tokens"

Параметры:

Documentation Enforcement (Phase 49.1-49.2.1)

ARC имеет встроенную систему, которая держит документацию в актуальном состоянии без human reminders. Работает вместе с pre-push git hook (scripts/check-docs-coverage.ts).

arc wrapup

Read-only checklist — показывает, какие docs требуют обновления для unpushed commits.

arc wrapup

Делегирует в scripts/check-docs-coverage.ts. Mapping:

arc wrapup --generate

Auto-draft skeleton entries для отсутствующих docs. Записывает TODO-marked stubs в:

• learnings.md — timestamp + auto-detected scope (api/backend/frontend/infra/process)
• docs/ROADMAP.md — Phase NN heading + commit summary
• docs/status/current-state.json — version bump + prepended change

arc wrapup --generate
# далі: review через `git diff`, заміни TODO на реальний контент, commit

TODO маркеры намеренно не пройдут review — генерируется структура, не содержимое.

arc wrapup --from-summary "<text>"

Capture research/decision/finding напрямую в learnings.md без коммита кода. Закрывает blind spot для работы без code commits (capacity analysis, broker comparison, trade-off review).

arc wrapup --from-summary "Decision: rejected Redis for single-VPS — broker overhead unjustified for 10KB/msg, 1-to-1 FIFO. fs.watch sufficient."

CLI auto-classifies:

• Type: decision / lesson / finding / spike (regex hints)
• Scope: infra / perf / security / api / frontend / process

Формат записи:

- [2026-04-28T15:00:00.000Z] [perf] Decision: ...

GitHub Integration (Phase 49.3)

Webhook-based notifications + UI feed для привязанных GitHub repos.

arc github link <project> <owner/repo>

Привязать repo к проекту. Возвращает webhook URL, secret и пошаговые инструкции для GitHub repo Settings → Webhooks.

arc github link arc-v2 SerhiiInUa/citadel-v2

Вывод:

✓ Repo linked.

Webhook URL:    https://arc-os.co/api/webhooks/github
Webhook secret: <32-byte hex>

Setup instructions:
  1. Go to https://github.com/SerhiiInUa/citadel-v2/settings/hooks
  2. Click "Add webhook"
  3. Payload URL: https://arc-os.co/api/webhooks/github
  4. Content type: application/json
  5. Secret: <secret>
  6. Events: Push, Pull requests, Workflow runs, Issues

arc github links [project]

Список привязанных repos для проекта (default: ARC_PROJECT env).

arc github links arc-v2

arc github unlink <project> <id>

Удали link по id (из arc github links).

arc github unlink arc-v2 3

Поддерживаемые события: push, pull_request, workflow_run, issues (95% use cases).

Что получаешь после setup:

• Telegram уведомление project owner на каждое событие (icon + summary + GitHub link)
• Sidebar feed в Workspace ContextRail (polls 30s, последние 8 events)

Подробный setup гайд: GitHub Integration Setup.

Нейронная память

arc memory refresh

Полная пересинхронизация всех источников знаний проекта с NotebookLM.

arc memory refresh

Вывод:

Refreshing neural memory...
Synced: 12 | Errors: 0

Sources:
  - wiki/architecture.md
  - wiki/deploy-guide.md
  - issues/open

Timeout: 30 секунд (увеличен из-за объёма синхронизации).

arc memory fetch-artifact [--type <artifact_type>]

Загрузить артефакт из NotebookLM (аудио-обзор и т.д.).

arc memory fetch-artifact                          # audio_overview за замовчуванням
arc memory fetch-artifact --type audio_overview    # явно вказати тип

Timeout: 60 секунд.

Переменные окружения

Устанавливаются автоматически при arc start, но можно задать вручную для использования subcommands вне сессии.

Пример ручного использования (вне arc start):

export ARC_PROJECT=my-project
export ARC_SERVER_URL=https://arc-os.co
export ARC_TOKEN=eyJhbGciOiJIUzI1NiI...
arc issues
arc learnings

Мониторинг сессий

При arc start автоматически запускается background watcher, который:

1. Находит новый .jsonl файл в ~/.claude/projects/{normalized-cwd}/
2. Каждые 3 секунды читает новые строки из transcript
3. Парсит user и assistant сообщения
4. Отправляет их на POST /api/cli/chat-log/:project (fire-and-forget)
5. Контент обрезается до 10 000 символов на сообщение

Watcher некритичен — ошибки игнорируются, сессия продолжает работать даже если CRM недоступен.

Примеры использования

Типичный рабочий процесс

# 1. Авторизуйся (одноразово)
arc login

# 2. Переглянь доступні проєкти
arc projects

# 3. Запусти сесію
arc my-project dev

# --- Усередині Claude сесії: ---

# 4. Переглянь відкриті задачі
arc issues

# 5. Створи нову задачу
arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"

# 6. Логуй прогрес
arc issue log 42 "Started implementation"
arc issue log 42 "Toggle component ready, testing system preference detection"

# 7. Оновлюй wiki
arc wiki update --file "architecture" --content "# Architecture\n\nUpdated with dark mode module..."

# 8. Оновлюй roadmap
arc roadmap sync --phase 45 --status "IN PROGRESS"

# 9. Завантаж навичку за потреби
arc skill crm-api-reference

# 10. Переглянь learnings
arc learnings

# 11. Закрий задачу
arc issue update 42 --status closed

# 12. Відправ звіт
arc report --summary "Implemented dark mode with system preference detection" \
  --files "theme.ts,App.tsx,DarkModeToggle.tsx" \
  --decisions "Used CSS custom properties for theming"

Синхронизация памяти

arc memory refresh
arc memory fetch-artifact --type audio_overview

Работа с несколькими проектами

# Сессия для первого проекта
arc project-alpha dev

# В другом терминале — сессия для второго
arc project-beta dev --role clceo

Timeouts