ARC CLI — Référence des commandes

ARC CLI — un outil en ligne de commande pour interagir avec Arc Cloud. Gère tes projets, issues, wiki et skills directement depuis le terminal.

• Code source : clients/arc-cli.ts
• Client API : clients/lib/api.ts
• Build : scripts/build-arc.sh (binary compilé)

Installation et configuration

La configuration est stockée dans ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

Authentification via device code flow. Ouvre le navigateur pour confirmation.

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

Après le lancement, le CLI affiche une URL et un code à usage unique. Ouvre l'URL dans ton navigateur, confirme l'autorisation — le CLI récupère automatiquement le token.

arc login --token <token>

Authentification directe par token (pour l'automatisation ou quand le device flow n'est pas disponible).

arc login --token eyJhbGciOiJIUzI1NiI...

Le CLI valide le token via l'API avant de le sauvegarder.

arc logout

Supprime les credentials de ~/.arc/config.json et retire le bloc ARC de CLAUDE.md (si présent).

arc logout

arc projects

Liste les projets disponibles sur le serveur.

arc projects

Sortie :

Available projects:

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

Démarrer une session

arc <project> [mode]

Initialise une session Claude avec le contexte complet du projet. Équivalent de arc start <project> [mode].

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

Ce qui se passe au démarrage :

1. Requête GET /api/cli/init/:project/:mode — récupération de CLAUDE.md, worker config, skills
2. Session-start picker (issue #115) — sélection interactive de l'issue active pour la session : open issues (tri P0→P3 + recent-first, filtre fuzzy si >10), recently-closed (avec reopen-confirm au pick), [n] Crée une nouvelle, [q] passe avec double-confirm. L'id sélectionné est stocké dans ~/.arc/sessions/<project>-<worker>.json sous active_issue_id
3. Injection du contexte dans le CLAUDE.md local (bloc ARC Cloud + bloc Active issue: #N — Title)
4. La variable d'env ARC_ACTIVE_ISSUE_ID=<id> est transmise au subprocess Claude — l'outil Bash la voit pour arc issue log sans re-prompt
5. Nettoyage des entrées .mcp.json dépréciées (si présentes)
6. Lancement du subprocess claude avec interactivité TTY
7. Démarrage du watcher en arrière-plan (voir "Surveillance des sessions")

Paramètres :

Bypass non-interactif : ARC_ISSUE_ID=42 arc my-project dev passe le picker et utilise l'id spécifié (pour CI/scripts).

Switch en cours de session : arc issue switch <id> (depuis un terminal parallèle) change l'issue active — écrit switched_away sur le précédent + switched_in sur le nouveau. La session en cours prendra le nouvel id au prochain redémarrage.

arc continue <project> [mode]

Reprend la dernière session Claude Code (fenêtre de 24 h). Restaure automatiquement active_issue_id sans re-prompt.

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

arc tour

Onboarding interactif en 5 étapes dans le terminal (miroir de la checklist web). La progression se synchronise avec le dashboard web.

arc tour

Gestion des issues

arc issues [--status <filter>]

Liste les issues du projet.

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

Sortie :

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]

Crée une nouvelle issue.

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

Paramètres :

arc issue update <id> [options]

Met à jour une issue existante.

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"

Paramètres :

Au moins un paramètre est requis pour la mise à jour.

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

Ajoute une entrée de progression à l'issue (activity log).

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

Paramètres :

Le backend (POST /api/mcp/issues/:project/:id/log) accepte les champs optionnels type (whitelist : log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) et ts (ISO-8601 pour les entrées backdatées, les dates futures sont clampées à now). Utilisé en interne par le session-start picker (#115) et arc retro (#117).

arc issue switch <id>

Change l'issue active pour la session en cours (issue #115). Enregistre dans ~/.arc/sessions/<project>-<worker>.json, écrit switched_away sur l'issue précédente + switched_in sur la nouvelle.

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

Validation : l'issue doit exister et être open. Si elle est fermée — exécute d'abord arc issue update <id> --status open.

arc retro <project> [options]

Reconstruit des issues rétroactivement à partir de l'historique de sessions + git log (issue #117). Scanne ~/.arc/sessions/<project>-*.json, lit le premier prompt utilisateur depuis les JSONL de transcript, collecte les commits via 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

Ce qui est ignoré automatiquement :

Ce qui se passe avec --apply :

1. createIssue pour chaque candidat (priority=P2, label=retro)
2. Entrées d'activité backdatées : session_start (started_at) + auto_summary par commit (timestamp du commit) + session_end (ended_at) — via POST /log avec le champ ts
3. Sessions >30 jours avec commits → status=closed immédiatement. Sessions récentes non terminées → status=open.

Skills et connaissances

arc skill <name>

Charge un skill depuis le Cloud. Affiche les instructions du skill et ses evals (si présentes).

arc skill consultant_system
arc skill crm-api-reference

La variable ARC_PROJECT est requise (définie automatiquement avec arc start).

Si le skill est introuvable, le CLI affiche la liste des skills disponibles.

arc kb search "<query>"

Recherche dans le wiki du projet. Correspondance par mots-clés sur les noms de fichiers, retourne jusqu'à 5 meilleurs résultats (contenu tronqué à 2000 caractères).

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

arc learnings

Règles accumulées et corrections de toutes les sessions du projet.

arc learnings

Sortie :

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

Wiki et Roadmap

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

Crée ou met à jour une page wiki du projet.

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

Paramètres :

Sortie : Wiki created: architecture.md (342 bytes) ou Wiki updated: ...

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

Met à jour le statut d'une phase dans le roadmap du projet.

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

Paramètres :

Rapports

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

Envoie un rapport de session vers 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"

Paramètres :

Application de la documentation (Phase 49.1-49.2.1)

ARC intègre un système qui maintient la documentation à jour sans rappels humains. Il fonctionne avec le pre-push git hook (scripts/check-docs-coverage.ts).

arc wrapup

Checklist en lecture seule — affiche quels docs doivent être mis à jour pour les commits non poussés.

arc wrapup

Délègue à scripts/check-docs-coverage.ts. Mapping :

arc wrapup --generate

Génère automatiquement des entrées skeleton pour les docs manquants. Écrit des stubs marqués TODO dans :

• learnings.md — timestamp + scope auto-détecté (api/backend/frontend/infra/process)
• docs/ROADMAP.md — heading Phase NN + résumé du commit
• docs/status/current-state.json — bump de version + changement prépendu

arc wrapup --generate
# ensuite : révise via `git diff`, remplace les TODO par du vrai contenu, commit

Les marqueurs TODO ne passeront intentionnellement pas la revue — c'est la structure qui est générée, pas le contenu.

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

Capture une recherche/décision/finding directement dans learnings.md sans commit de code. Comble l'angle mort pour le travail sans commits de code (analyse de capacité, comparaison de brokers, revue de trade-offs).

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

Le CLI auto-classifie :

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

Format de l'entrée :

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

Intégration GitHub (Phase 49.3)

Notifications basées sur webhooks + fil d'actualité UI pour les repos GitHub liés.

arc github link <project> <owner/repo>

Lie un repo à un projet. Retourne l'URL du webhook, le secret, et des instructions étape par étape pour GitHub repo Settings → Webhooks.

arc github link arc-v2 SerhiiInUa/citadel-v2

Sortie :

✓ 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 les repos liés pour un projet (par défaut : variable env ARC_PROJECT).

arc github links arc-v2

arc github unlink <project> <id>

Supprime un lien par id (depuis arc github links).

arc github unlink arc-v2 3

Événements supportés : push, pull_request, workflow_run, issues (95% des cas d'usage).

Ce que tu obtiens après la configuration :

• Notification Telegram au propriétaire du projet pour chaque événement (icône + résumé + lien GitHub)
• Fil d'actualité dans la Workspace ContextRail du dashboard (polling toutes les 30s, 8 derniers événements)

Guide de configuration détaillé : GitHub Integration Setup.

Mémoire neurale

arc memory refresh

Resynchronisation complète de toutes les sources de connaissances du projet avec NotebookLM.

arc memory refresh

Sortie :

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

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

Timeout : 30 secondes (augmenté en raison du volume de synchronisation).

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

Télécharge un artefact depuis NotebookLM (audio overview, etc.).

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

Timeout : 60 secondes.

Variables d'environnement

Définies automatiquement avec arc start, mais peuvent être renseignées manuellement pour utiliser les sous-commandes hors session.

Exemple d'utilisation manuelle (hors arc start) :

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

Surveillance des sessions

Au démarrage de arc start, un watcher en arrière-plan se lance automatiquement et :

1. Trouve le nouveau fichier .jsonl dans ~/.claude/projects/{normalized-cwd}/
2. Toutes les 3 secondes, lit les nouvelles lignes du transcript
3. Parse les messages user et assistant
4. Les envoie vers POST /api/cli/chat-log/:project (fire-and-forget)
5. Le contenu est tronqué à 10 000 caractères par message

Le watcher est non critique — les erreurs sont ignorées, la session continue même si le CRM est indisponible.

Exemples d'utilisation

Flux de travail typique

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

Synchronisation de la mémoire

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

Travailler avec plusieurs projets

# Session pour le premier projet
arc project-alpha dev

# Dans un autre terminal — session pour le second
arc project-beta dev --role clceo

Timeouts