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

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

• Вихідний код: clients/arc-cli.ts
• API-клієнт: clients/lib/api.ts
• Збірка: scripts/build-arc.sh (скомпільований бінарник)

Встановлення та налаштування

Конфігурація зберігається в ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

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

arc login                          # default server: https://arc-os.co
arc login https://my-server.com    # custom server

Після запуску CLI виводить URL і одноразовий код. Відкрий URL у браузері, підтверди авторизацію — CLI отримає токен автоматично.

arc login --token <token>

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

arc login --token eyJhbGciOiJIUzI1NiI...

CLI валідує токен проти API перед збереженням.

arc logout

Видаляє облікові дані з ~/.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 completion <shell>

Згенеруй скрипт автодоповнення для bash, zsh або fish. Tab-доповнення охоплює підкоманди, назви твоїх проєктів, воркерів кожного проєкту та підкоманди arc issue.

# bash — add to ~/.bashrc
eval "$(arc completion bash)"

# zsh — write to a directory on your $fpath, or eval in ~/.zshrc
arc completion zsh > "${fpath[1]}/_arc"

# fish
arc completion fish > ~/.config/fish/completions/arc.fish

Після встановлення:

arc <TAB>            → subcommands + your project names
arc <project> <TAB>  → that project's workers
arc issue <TAB>      → create / log / update / switch / take / show

Назви проєктів і воркерів підтягуються із сервера й кешуються на 60с у ~/.arc/completion-cache.json; доповнення залишається тихим (ніколи не блокує shell), якщо ти офлайн або не залогінений.

Запуск сесії

arc <project> [mode]

Ініціалізує сесію Claude з повним контекстом проєкту. Еквівалент arc start <project> [mode].

arc my-project dev             # dev mode (default)
arc my-project prod            # prod mode
arc --role clceo my-project    # with the CEO role

Що відбувається під час запуску:

1. Запит GET /api/cli/init/:project/:mode — підтягує CLAUDE.md, конфіг воркера, скіли
2. Session-start picker (issue #115) — інтерактивний вибір активної задачі для сесії: відкриті задачі (відсортовані P0→P3 + спершу недавні, fuzzy-фільтр якщо >10), нещодавно закриті (з підтвердженням reopen при виборі), [n] створити нову, [q] пропустити з подвійним підтвердженням. Обраний id зберігається в ~/.arc/sessions/<project>-<worker>.json як active_issue_id
3. Інжекція контексту в локальний CLAUDE.md (блок ARC Cloud + блок Active issue: #N — Title)
4. Env-змінна ARC_ACTIVE_ISSUE_ID=<id> передається в підпроцес Claude — інструмент Bash бачить її для arc issue log без повторного запиту
5. Очищення застарілих записів .mcp.json (якщо є)
6. Запуск підпроцесу claude з TTY-інтерактивністю
7. Старт фонового watcher'а (див. "Моніторинг сесії")

Параметри:

Неінтерактивний обхід: ARC_ISSUE_ID=42 arc my-project dev пропускає picker і використовує заданий id (для CI/скриптів).

Перемикання посеред сесії: arc issue switch <id> (з паралельного терміналу) перемикає активну задачу — записує switched_away для попередньої задачі + switched_in для нової. Поточна сесія підхоплює новий id після рестарту.

arc continue <project> [mode]

Відновити останню сесію Claude Code (вікно 24 години). Автоматично відновлює active_issue_id без повторного запиту.

arc continue my-project             # pick up the previous session + active issue
arc continue my-project --reselect-issue   # force re-run picker

arc tour

Інтерактивний 5-кроковий онбординг у терміналі (дзеркалить веб-чеклист). Прогрес синхронізується з веб-дашбордом.

arc tour

Керування задачами

arc issues [--status <filter>]

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

arc issues                    # open only (default)
arc issues --status closed    # closed only
arc issues --status all       # all issues

Вивід:

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

Додати запис прогресу до задачі (лог активності).

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

Параметри:

Бекенд (POST /api/mcp/issues/:project/:id/log) приймає необов'язкові поля type (whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) і ts (ISO-8601 для записів заднім числом; значення в майбутньому обрізаються до 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   # for a specific worker (default: developer)

Валідація: задача має існувати й бути open. Якщо вона закрита — спершу запусти arc issue update <id> --status open.

arc sessions <project> [mode]

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

arc sessions arc-v2                    # all workers
arc sessions arc-v2 --worker developer # developer only

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

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

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

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

Продовження на іншій машині — arc sessions <project> --from-server

Підхопи сесію, яку почав на іншому комп'ютері. Твої сесії живуть на машині, де ти їх запускав (~/.claude); ця команда підтягує одну з сервера й реконструює її локально, щоб claude --resume міг під'єднатися.

arc sessions arc-v2 --from-server

Передумова: увімкни Account Settings → "Upload session transcripts" (за замовчуванням вимкнено). З увімкненим прапорцем arc завантажує транскрипт кожної завершеної сесії на сервер. Транскрипти можуть містити код і секрети — читати їх можеш лише ти, і вони видаляються разом із твоїм акаунтом.

Picker виводить список завантажених транскриптів (session-id, воркер, вік, перший промт, кількість повідомлень). Введи номер рядка або префікс session-id з 8 символів; arc завантажує транскрипт, записує його в ~/.claude цієї машини й продовжує — так само, як локальне resume.

Запускай це з того самого робочого каталогу, який використовуєш для проєкту: claude --resume знаходить транскрипт за поточною текою, тож arc записує файл у ту теку, в якій ти перебуваєш.

arc retro <project> [options]

Реконструюй задачі заднім числом з історії сесій + git log (issue #117). Сканує ~/.arc/sessions/<project>-*.json, читає перший промт користувача з транскрипту JSONL, збирає коміти через git log --since=started_at --until=ended_at.

arc retro gapap                       # dry-run — prints the plan
arc retro gapap --apply               # creates issues
arc retro gapap --since 2026-01-01    # only after this date
arc retro gapap --worker consultant   # only for one worker

Що пропускається автоматично:

Що відбувається на --apply:

1. createIssue для кожного кандидата (priority=P2, label=retro)
2. Записи активності заднім числом: session_start (started_at) + auto_summary на кожен коміт (час коміту) + session_end (ended_at) — через POST /log з полем ts
3. Сесії старші за 30 днів із комітами → status=closed одразу. Недавні незавершені → 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>"

Шукай у вікі проєкту. Збіг за ключовими словами в іменах файлів; повертає до 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

Вікі та роадмап

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

Онови статус фази в роадмапі проєкту.

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"

Параметри:

Контроль документації (Phase 49.1-49.2.1)

У ARC є вбудована система, що тримає документацію актуальною без нагадувань від людини. Вона працює разом із pre-push git hook'ом (scripts/check-docs-coverage.ts).

arc wrapup

Read-only чекліст — показує, які документи треба оновити для непушнутих комітів.

arc wrapup

Делегує до scripts/check-docs-coverage.ts. Мапінг:

arc wrapup --generate

Авто-чернетка skeleton-записів для відсутніх документів. Записує TODO-marked заготовки в:

• learnings.md — timestamp + авто-визначений scope (api/backend/frontend/infra/process)
• docs/ROADMAP.md — заголовок Phase NN + підсумок коміту
• docs/status/current-state.json — bump версії + дописана зміна

arc wrapup --generate
# then: review via `git diff`, replace TODOs with real content, commit

TODO-маркери навмисно не пройдуть рев'ю — структура генерується, а не вміст.

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

Зафіксуй дослідження/рішення/знахідку прямо в learnings.md без коміту коду. Закриває сліпу зону для роботи без комітів коду (аналіз потужності, порівняння брокерів, огляд trade-off'ів).

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

CLI авто-класифікує:

• Тип: decision / lesson / finding / spike (regex-підказки)
• Scope: infra / perf / security / api / frontend / process

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

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

Інтеграція з GitHub (Phase 49.3)

Сповіщення на основі вебхуків + стрічка в UI для прив'язаних GitHub-репозиторіїв.

arc github link <project> <owner/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]

Список репозиторіїв, прив'язаних до проєкту (за замовчуванням: env ARC_PROJECT).

arc github links arc-v2

arc github unlink <project> <id>

Видали прив'язку за id (з arc github links).

arc github unlink arc-v2 3

Підтримувані події: push, pull_request, workflow_run, issues (95% сценаріїв).

Що ти отримуєш після налаштування:

• Сповіщення в Telegram власнику проєкту на кожну подію (іконка + summary + посилання на GitHub)
• Стрічка в сайдбарі в ContextRail робочого простору (опитування 30с, останні 8 подій)

Детальний посібник з налаштування: Налаштування інтеграції з GitHub.

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

arc memory refresh

Phase 71.8 (#365): повторно ембедни всі ключові джерела знань проєкту (MANIFEST + ROADMAP + вікі + відкриті задачі) у самохостингований RAG-сховище (embeddings + embeddings_vec). Той самий ендпоінт, нова семантика — записує в локальний SQLite, а не в Google NotebookLM.

arc memory refresh

Вивід:

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

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

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

Цей крок зазвичай не потрібен — хуки Phase 71.5 автоматично ембедять кожен запис вікі/задачі/скілу. arc memory refresh корисний як "force re-index" після масового pull або міграції.

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

Аудіо-огляд NotebookLM не має RAG-еквівалента. Ендпоінт повертає 410 Gone. Якщо потрібен голосовий підсумок — дивись майбутню Phase для Whisper TTS по вікі проєкту.

Env-змінні

Встановлюються автоматично через arc start, але їх можна задати вручну, щоб використовувати підкоманди поза сесією.

Приклад ручного використання (поза 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 автоматично запускається фоновий watcher, який:

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

Watcher некритичний — помилки ігноруються, і сесія продовжує працювати, навіть якщо CRM недоступний.

Приклади використання

Типовий робочий процес

# 1. Log in (one-time)
arc login

# 2. View available projects
arc projects

# 3. Start a session
arc my-project dev

# --- Inside the Claude session: ---

# 4. View open issues
arc issues

# 5. Create a new issue
arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"

# 6. Log progress
arc issue log 42 "Started implementation"
arc issue log 42 "Toggle component ready, testing system preference detection"

# 7. Update the wiki
arc wiki update --file "architecture" --content "# Architecture\n\nUpdated with dark mode module..."

# 8. Update the roadmap
arc roadmap sync --phase 45 --status "IN PROGRESS"

# 9. Load a skill when needed
arc skill crm-api-reference

# 10. View learnings
arc learnings

# 11. Close the issue
arc issue update 42 --status closed

# 12. Send a report
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

Робота з кількома проєктами

# Session for the first project
arc project-alpha dev

# In another terminal — a session for the second one
arc project-beta dev --role clceo

Таймаути