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. Injection контексту в локальний CLAUDE.md (ARC Cloud block)
3. Очищення deprecated .mcp.json записів (якщо є)
4. Запуск claude subprocess з TTY interactivity
5. Старт background watcher (див. "Моніторинг сесій")

Параметри:

Управління задачами (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"

Параметри:

Навички та знання

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>"

Захоплення 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 нотифікації + 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, що раніше синхронізував з NotebookLM, тепер пише в локальну SQLite.

arc memory refresh

Вивід:

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

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

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

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

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

NotebookLM audio overview не має RAG-еквівалента. Endpoint повертає 410 Gone.

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

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