ARC CLI — Référence des commandes

ARC CLI est l'outil en ligne de commande pour interagir avec Arc Cloud. Gère les projets, issues, wiki et skills directement depuis ton terminal.

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

Installation et configuration

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

arc login [server_url]

Autorisation via device code flow. Ouvre un navigateur pour confirmation.

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

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

arc login --token <token>

Autorisation directe par token (pour l'automatisation ou quand le device flow est indisponible).

arc login --token eyJhbGciOiJIUzI1NiI...

Le CLI valide le token contre l'API avant de l'enregistrer.

arc logout

Retire les identifiants de ~/.arc/config.json et supprime le bloc ARC du CLAUDE.md (s'il est 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

arc completion <shell>

Émet un script de complétion pour bash, zsh ou fish. La complétion par tabulation couvre les sous-commandes, les noms de tes projets, les workers de chaque projet, et les sous-commandes de 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

Une fois installé :

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

Les noms de projets et de workers sont récupérés depuis le serveur et mis en cache 60s dans ~/.arc/completion-cache.json ; la complétion reste silencieuse (ne bloque jamais le shell) si tu es hors ligne ou non connecté.

Démarrer une session

arc <project> [mode]

Initialise une session Claude avec le contexte complet du projet. Équivalent à 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

Ce qui se passe au lancement :

1. Requête GET /api/cli/init/:project/:mode — récupère CLAUDE.md, config des workers, skills
2. Picker de démarrage de session (issue #115) — sélection interactive de l'issue active pour la session : issues ouvertes (triées P0→P3 + récentes d'abord, filtre flou si >10), récemment fermées (avec confirmation de réouverture à la sélection), [n] créer une nouvelle, [q] passer avec double confirmation. L'id sélectionné est stocké dans ~/.arc/sessions/<project>-<worker>.json comme 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 passée au sous-processus Claude — l'outil Bash la voit pour arc issue log sans redemander
5. Nettoyage des entrées .mcp.json obsolètes (s'il y en a)
6. Lancement du sous-processus claude avec interactivité TTY
7. Démarrage du watcher d'arrière-plan (voir « Surveillance de session »)

Paramètres :

Contournement non interactif : ARC_ISSUE_ID=42 arc my-project dev saute le picker et utilise l'id donné (pour CI/scripts).

Changement en cours de session : arc issue switch <id> (depuis un terminal parallèle) change l'issue active — il écrit switched_away sur l'issue précédente + switched_in sur la nouvelle. La session courante prend le nouvel id après un redémarrage.

arc continue <project> [mode]

Reprendre la dernière session Claude Code (fenêtre de 24 heures). Restaure automatiquement active_issue_id sans redemander.

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

arc tour

Onboarding interactif en 5 étapes dans le terminal (reflète 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 only (default)
arc issues --status closed    # closed only
arc issues --status all       # all issues

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 une mise à jour.

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

Ajoute une entrée de progression à une issue (log d'activité).

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 antidatées ; les valeurs futures sont ramenées à now). Utilisé en interne par le picker de démarrage de session (#115) et arc retro (#117).

arc issue switch <id>

Change l'issue active pour la session courante (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   # for a specific worker (default: developer)

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

arc sessions <project> [mode]

Affiche toutes les sessions enregistrées d'un projet et reprends l'une d'elles à la demande — même si tu as oublié de lancer continue (issue #131).

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

Affiche une table : statut du transcript (● présent / ✗ perdu), nom du worker, session-id court, âge de la session, issue active. En dessous — une liste de tous les fichiers .jsonl, y compris les « orphelins » (non liés au worker courant).

Après la table — un picker interactif :

• Saisis un nom de worker (developer, sentinel…) — reprend la dernière session de ce worker
• Saisis les 8 caractères d'un session-id — reprend cette session précise
• Enter — passer

Comment ça marche : le picker écrit le session_id + transcript_path choisi dans ~/.arc/sessions/<project>-<worker>.json, puis lance un arc <project> continue classique.

Continuer sur une autre machine — arc sessions <project> --from-server

Reprends une session que tu as démarrée sur un autre ordinateur. Tes sessions vivent sur la machine où tu les as exécutées (~/.claude) ; ceci en télécharge une depuis le serveur et la réhydrate localement pour que claude --resume puisse s'y rattacher.

arc sessions arc-v2 --from-server

Prérequis : active Account Settings → « Upload session transcripts » (désactivé par défaut). Avec cette option activée, arc uploade le transcript de chaque session terminée vers le serveur. Les transcripts peuvent contenir du code et des secrets — toi seul peux les lire, et ils sont supprimés avec ton compte.

Le picker liste tes transcripts uploadés (session-id, worker, âge, premier prompt, nombre de messages). Saisis un numéro de ligne ou un préfixe de session-id de 8 caractères ; arc télécharge le transcript, l'écrit dans le ~/.claude de cette machine, et le continue — comme une reprise locale.

Lance-le depuis le même répertoire de travail que celui que tu utilises pour le projet : claude --resume localise un transcript d'après le dossier courant, donc arc écrit le fichier dans le dossier où tu te trouves.

arc retro <project> [options]

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

Ce qui est sauté automatiquement :

Ce qui se passe avec --apply :

1. createIssue pour chaque candidat (priority=P2, label=retro)
2. Entrées d'activité antidatées : session_start (started_at) + auto_summary par commit (horodatage du commit) + session_end (ended_at) — via POST /log avec le champ ts
3. Sessions de plus de 30 jours avec des commits → status=closed immédiatement. Récentes et inachevées → status=open.

Skills et connaissances

arc skill <name>

Charge un skill depuis Cloud. Affiche les instructions et les evals du skill (s'il y en a).

arc skill consultant_system
arc skill crm-api-reference

Nécessite la variable ARC_PROJECT (définie automatiquement par 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 mot-clé sur les noms de fichiers ; renvoie jusqu'à 5 meilleurs résultats (contenu tronqué à 2000 caractères).

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

arc learnings

Règles et corrections accumulées 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 de wiki de 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 la roadmap du projet.

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

Paramètres :

Reporting

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

Envoie un rapport de session à 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 dispose d'un système intégré qui maintient la documentation à jour sans rappels humains. Il fonctionne de concert avec le hook git pre-push (scripts/check-docs-coverage.ts).

arc wrapup

Checklist en lecture seule — montre quelles docs doivent être mises à jour pour les commits non poussés.

arc wrapup

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

arc wrapup --generate

Ébauche automatiquement des entrées squelettes pour les docs manquantes. Écrit des stubs marqués TODO dans :

• learnings.md — horodatage + périmètre auto-détecté (api/backend/frontend/infra/process)
• docs/ROADMAP.md — titre Phase NN + résumé du commit
• docs/status/current-state.json — bump de version + changement ajouté en tête

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

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

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

Capture une recherche/décision/conclusion directement dans learnings.md sans commit de code. Comble l'angle mort du travail sans commit (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 classe automatiquement :

• Type : decision / lesson / finding / spike (indices regex)
• Périmètre : infra / perf / security / api / frontend / process

Format d'entrée :

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

Intégration GitHub (Phase 49.3)

Notifications par webhook + feed UI pour les repos GitHub liés.

arc github link <project> <owner/repo>

Lie un repo à un projet. Renvoie l'URL du webhook, le secret, et les instructions pas à pas 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 à un projet (par défaut : env ARC_PROJECT).

arc github links arc-v2

arc github unlink <project> <id>

Retire 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 à chaque événement (icône + résumé + lien GitHub)
• Feed dans la sidebar du ContextRail du Workspace (polling 30s, 8 derniers événements)

Guide de configuration détaillé : Configuration de l'intégration GitHub.

Mémoire neuronale

arc memory refresh

Phase 71.8 (#365) : re-embed toutes les sources de connaissances clés du projet (MANIFEST + ROADMAP + wiki + issues ouvertes) dans le store RAG auto-hébergé (embeddings + embeddings_vec). Même endpoint, nouvelle sémantique — écrit dans le SQLite local, pas vers Google 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 (le volume d'appels embed vers Cohere pour un re-embed complet).

Cette étape est généralement inutile — les hooks de la Phase 71.5 re-embed automatiquement chaque écriture wiki/issue/skill. arc memory refresh est utile comme « ré-indexation forcée » après un pull massif ou une migration.

arc memory fetch-artifact — supprimé en Phase 71.8

L'audio overview NotebookLM n'a pas d'équivalent RAG. L'endpoint renvoie 410 Gone. Si tu as besoin d'un résumé vocal — vois une future Phase pour Whisper TTS sur le wiki du projet.

Variables d'environnement

Définies automatiquement par arc start, mais tu peux les définir manuellement pour utiliser les sous-commandes hors d'une 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 de session

Au arc start, un watcher d'arrière-plan se lance automatiquement et :

1. Trouve le nouveau fichier .jsonl dans ~/.claude/projects/{normalized-cwd}/
2. Lit les nouvelles lignes du transcript toutes les 3 secondes
3. Parse les messages user et assistant
4. Les envoie à 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, et la session continue de fonctionner même si le CRM est indisponible.

Exemples d'utilisation

Workflow typique

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

Synchronisation de la mémoire

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

Travailler avec plusieurs projets

# Session for the first project
arc project-alpha dev

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

Timeouts