ARC CLI — Довідник команд

ARC CLI — інструмент командного рядка для взаємодії з Arc Cloud. Керуй проєктами, задачами, wiki та навичками прямо з терміналу.

• Вихідний код: 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) — інтерактивний вибір активного issue для сесії: 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> (з паралельного терміналу) перемикає активний issue — пише 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 dashboard.

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 для поточної сесії (issue #115). Зберігає в ~/.arc/sessions/<project>-<worker>.json, пише switched_away на попередньому issue + switched_in на новому.

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

Validation: issue має існувати + бути open. Якщо закритий — спочатку arc issue update <id> --status open.

arc sessions <project> [mode]

Переглянути всі збережені сесії для проєкту і за потреби відновити будь-яку з них — навіть якщо забув вказати continue (issue #131).

arc sessions arc-v2                    # всі воркери
arc sessions arc-v2 --worker developer # тільки developer

Виводить таблицю: статус транскрипту (● є / ✗ втрачений), ім'я воркера, короткий session-id, вік сесії, активний issue. Нижче — список усіх .jsonl файлів, включаючи "осиротілі" (не прив'язані до поточного воркера).

Після таблиці — інтерактивний picker:

• Введи ім'я воркера (developer, sentinel…) — відновить останню сесію цього воркера
• Введи 8 символів session-id — відновить конкретну сесію
• Enter — пропустити

Як це працює: picker записує обраний session_id + transcript_path у ~/.arc/sessions/<project>-<worker>.json, після чого запускає звичайний arc <project> continue.

arc retro <project> [options]

Реконструювати issues 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 field
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>"

Пошук по wiki проєкту. 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

Wiki та Roadmap

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

Створити або оновити wiki-сторінку проєкту.

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

Entry формат:

- [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, та step-by-step інструкції для 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

Phase 71.8 (#365): re-embed усі ключові джерела знань проєкту (MANIFEST + ROADMAP + wiki + open issues) у self-hosted RAG store (embeddings + embeddings_vec). Той самий endpoint, нова семантика — пише до локальної SQLite, а не до Google NotebookLM.

arc memory refresh

Вивід:

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

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

Timeout: 30 секунд (обсяг embed-викликів до Cohere для повного re-embed).

Зазвичай цей крок не потрібен — Phase 71.5 hooks автоматично re-embed-ять кожен запис wiki/issue/skill. arc memory refresh корисний як "force re-index" після masовoго pull або міграції.

arc memory fetch-artifact — видалено у Phase 71.8

NotebookLM audio overview не має RAG-еквівалента. Endpoint повертає 410 Gone. Якщо потрібен голосовий summary — див. майбутню Phase для Whisper TTS over project wiki.

Змінні середовища

Встановлюються автоматично при 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