ARC CLI — Befehlsreferenz

ARC CLI — ein Befehlszeilentool zur Interaktion mit Arc Cloud. Verwalte Projekte, Issues, Wiki und Skills direkt im Terminal.

• Quellcode: clients/arc-cli.ts
• API-Client: clients/lib/api.ts
• Build: scripts/build-arc.sh (kompiliertes Binary)

Installation und Konfiguration

Die Konfiguration wird in ~/.arc/config.json gespeichert (server_url, token, connected_at).

arc login [server_url]

Authentifizierung über den Device-Code-Flow. Öffnet den Browser zur Bestätigung.

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

Nach dem Start gibt die CLI eine URL und einen Einmalcode aus. Öffne die URL im Browser, bestätige die Autorisierung — die CLI holt den Token automatisch.

arc login --token <token>

Direkte Token-Authentifizierung (für Automatisierung oder wenn der Device-Flow nicht verfügbar ist).

arc login --token eyJhbGciOiJIUzI1NiI...

Die CLI validiert den Token über die API, bevor er gespeichert wird.

arc logout

Löscht die Credentials aus ~/.arc/config.json und entfernt den ARC-Block aus CLAUDE.md (falls vorhanden).

arc logout

arc projects

Liste der verfügbaren Projekte auf dem Server.

arc projects

Ausgabe:

Available projects:

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

Sitzung starten

arc <project> [mode]

Initialisiert eine Claude-Sitzung mit dem vollständigen Projektkontext. Entspricht arc start <project> [mode].

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

Was beim Start passiert:

1. Anfrage GET /api/cli/init/:project/:mode — lädt CLAUDE.md, Worker-Konfiguration und Skills
2. Session-start picker (issue #115) — interaktive Auswahl des aktiven Issues für die Sitzung: offene Issues (sortiert P0→P3 + neueste zuerst, Fuzzy-Filter bei >10), kürzlich geschlossene (mit reopen-Bestätigung), [n] create new, [q] skip mit Double-Confirm. Die gewählte ID wird in ~/.arc/sessions/<project>-<worker>.json als active_issue_id gespeichert
3. Kontext-Injektion in das lokale CLAUDE.md (ARC-Cloud-Block + Active issue: #N — Title-Block)
4. ARC_ACTIVE_ISSUE_ID=<id> wird als Env-Variable an den Claude-Subprozess übergeben — das Bash-Tool sieht sie für arc issue log ohne erneute Eingabe
5. Bereinigung veralteter .mcp.json-Einträge (falls vorhanden)
6. Start des claude-Subprozesses mit TTY-Interaktivität
7. Start des Background-Watchers (siehe „Sitzungsmonitoring")

Parameter:

Non-interactive Bypass: ARC_ISSUE_ID=42 arc my-project dev überspringt den Picker und verwendet die angegebene ID (für CI/Skripte).

Mid-session-Wechsel: arc issue switch <id> (aus einem parallelen Terminal) wechselt das aktive Issue — schreibt switched_away auf das vorherige + switched_in auf das neue. Die laufende Sitzung übernimmt die neue ID nach einem Neustart.

arc continue <project> [mode]

Setzt die letzte Claude Code-Sitzung fort (24-Stunden-Fenster). Stellt active_issue_id automatisch ohne erneute Auswahl wieder her.

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

arc tour

Interaktives 5-Schritte-Onboarding im Terminal (spiegelt die Web-Checkliste). Der Fortschritt wird mit dem Web-Dashboard synchronisiert.

arc tour

Issue-Verwaltung

arc issues [--status <filter>]

Liste der Projekt-Issues.

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

Ausgabe:

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]

Erstellen eines neuen Issues.

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

Parameter:

arc issue update <id> [options]

Bestehendes Issue aktualisieren.

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"

Parameter:

Mindestens ein Parameter ist für die Aktualisierung erforderlich.

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

Einen Fortschrittseintrag zum Issue hinzufügen (Activity-Log).

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

Parameter:

Das Backend (POST /api/mcp/issues/:project/:id/log) akzeptiert die optionalen Felder type (Whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) und ts (ISO-8601 für backdatierte Einträge; zukünftige Zeitstempel werden auf „jetzt" geclampgt). Wird intern vom Session-Start-Picker (#115) und arc retro (#117) verwendet.

arc issue switch <id>

Wechselt das aktive Issue für die laufende Sitzung (issue #115). Speichert in ~/.arc/sessions/<project>-<worker>.json, schreibt switched_away auf das vorherige Issue + switched_in auf das neue.

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

Validierung: Das Issue muss existieren und open sein. Wenn es geschlossen ist — zuerst arc issue update <id> --status open ausführen.

arc retro <project> [options]

Issues retroaktiv aus der Sitzungshistorie + dem Git-Log rekonstruieren (issue #117). Scannt ~/.arc/sessions/<project>-*.json, liest die erste User-Prompt aus dem Transcript-JSONL und sammelt Commits über 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

Automatisch übersprungene Einträge:

Was bei --apply passiert:

1. createIssue für jeden Kandidaten (priority=P2, label=retro)
2. Backdatierte Activity-Einträge: session_start (started_at) + auto_summary pro Commit (Commit-Zeitstempel) + session_end (ended_at) — über POST /log mit ts-Feld
3. Sitzungen >30 Tage mit Commits → sofort status=closed. Kürzlich unabgeschlossene → status=open.

Skills und Wissen

arc skill <name>

Einen Skill aus der Cloud laden. Gibt die Skill-Anweisungen und Evals aus (falls vorhanden).

arc skill consultant_system
arc skill crm-api-reference

Die Variable ARC_PROJECT ist erforderlich (wird bei arc start automatisch gesetzt).

Wird der Skill nicht gefunden, gibt die CLI eine Liste der verfügbaren Skills aus.

arc kb search "<query>"

Suche im Projekt-Wiki. Keyword-Match auf Dateinamen, gibt bis zu 5 beste Ergebnisse zurück (Inhalt wird auf 2.000 Zeichen gekürzt).

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

arc learnings

Angesammelte Regeln und Korrekturen aus allen Projekt-Sitzungen.

arc learnings

Ausgabe:

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

Wiki und Roadmap

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

Eine Wiki-Seite des Projekts erstellen oder aktualisieren.

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

Parameter:

Ausgabe: Wiki created: architecture.md (342 bytes) oder Wiki updated: ...

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

Den Phasenstatus in der Projekt-Roadmap aktualisieren.

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

Parameter:

Berichte

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

Einen Sitzungsbericht an Arc Cloud senden.

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"

Parameter:

Documentation Enforcement (Phase 49.1-49.2.1)

ARC verfügt über ein eingebautes System, das die Dokumentation ohne manuelle Erinnerungen aktuell hält. Es arbeitet zusammen mit dem Pre-Push-Git-Hook (scripts/check-docs-coverage.ts).

arc wrapup

Read-only-Checkliste — zeigt an, welche Docs für nicht gepushte Commits aktualisiert werden müssen.

arc wrapup

Delegiert an scripts/check-docs-coverage.ts. Mapping:

arc wrapup --generate

Automatisch Skeleton-Einträge für fehlende Docs entwerfen. Schreibt TODO-markierte Stubs in:

• learnings.md — Zeitstempel + automatisch erkannter Scope (api/backend/frontend/infra/process)
• docs/ROADMAP.md — Phase-NN-Überschrift + Commit-Zusammenfassung
• docs/status/current-state.json — Version-Bump + vorangestellte Änderung

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

TODO-Marker bestehen den Review absichtlich nicht — es wird Struktur erzeugt, kein Inhalt.

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

Recherchen, Entscheidungen oder Erkenntnisse direkt in learnings.md festhalten, ohne Code-Commit. Schließt den blinden Fleck für Arbeit ohne Code-Commits (Kapazitätsanalysen, Broker-Vergleiche, Trade-off-Reviews).

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

Die CLI klassifiziert automatisch:

• Typ: decision / lesson / finding / spike (Regex-Hinweise)
• Scope: infra / perf / security / api / frontend / process

Eintragsformat:

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

GitHub-Integration (Phase 49.3)

Webhook-basierte Benachrichtigungen + UI-Feed für verknüpfte GitHub-Repos.

arc github link <project> <owner/repo>

Ein Repo mit einem Projekt verknüpfen. Gibt die Webhook-URL, das Secret und eine Schritt-für-Schritt-Anleitung für GitHub-Repo-Einstellungen → Webhooks zurück.

arc github link arc-v2 SerhiiInUa/citadel-v2

Ausgabe:

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

Liste der verknüpften Repos für ein Projekt (Standard: ARC_PROJECT-Env-Variable).

arc github links arc-v2

arc github unlink <project> <id>

Verknüpfung anhand der ID entfernen (aus arc github links).

arc github unlink arc-v2 3

Unterstützte Ereignisse: push, pull_request, workflow_run, issues (95 % der Anwendungsfälle).

Was du nach dem Setup erhältst:

• Telegram-Benachrichtigung an den Projekt-Owner bei jedem Ereignis (Icon + Zusammenfassung + GitHub-Link)
• Sidebar-Feed im Workspace ContextRail (polling alle 30 s, letzte 8 Ereignisse)

Detaillierter Setup-Guide: GitHub Integration Setup.

Neurales Gedächtnis

arc memory refresh

Vollständige Resynchronisierung aller Wissensquellen des Projekts mit NotebookLM.

arc memory refresh

Ausgabe:

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

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

Timeout: 30 Sekunden (erhöht aufgrund des Synchronisierungsumfangs).

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

Ein Artefakt aus NotebookLM laden (Audio-Übersicht usw.).

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

Timeout: 60 Sekunden.

Umgebungsvariablen

Werden bei arc start automatisch gesetzt, können aber auch manuell für Subcommands außerhalb einer Sitzung definiert werden.

Beispiel für manuelle Nutzung (außerhalb von arc start):

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

Sitzungsmonitoring

Bei arc start wird automatisch ein Background-Watcher gestartet, der:

1. Eine neue .jsonl-Datei in ~/.claude/projects/{normalized-cwd}/ findet
2. Alle 3 Sekunden neue Zeilen aus dem Transcript liest
3. user- und assistant-Nachrichten parst
4. Sie an POST /api/cli/chat-log/:project sendet (fire-and-forget)
5. Den Inhalt auf 10.000 Zeichen pro Nachricht kürzt

Der Watcher ist nicht kritisch — Fehler werden ignoriert, die Sitzung läuft weiter, auch wenn das CRM nicht erreichbar ist.

Anwendungsbeispiele

Typischer Workflow

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

Gedächtnis synchronisieren

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

Mit mehreren Projekten arbeiten

# Sitzung für das erste Projekt
arc project-alpha dev

# In einem anderen Terminal — Sitzung für das zweite
arc project-beta dev --role clceo

Timeouts