ARC CLI — Referencia de comandos

ARC CLI — herramienta de línea de comandos para interactuar con Arc Cloud. Gestiona proyectos, issues, wiki y skills directamente desde la terminal.

• Código fuente: clients/arc-cli.ts
• Cliente API: clients/lib/api.ts
• Build: scripts/build-arc.sh (binary compilado)

Instalación y configuración

La configuración se guarda en ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

Autorización mediante device code flow. Abre el navegador para confirmar.

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

Al ejecutar el comando, la CLI mostrará una URL y un código de un solo uso. Abre la URL en el navegador, confirma la autorización — la CLI obtendrá el token automáticamente.

arc login --token <token>

Autorización directa con token (para automatización o cuando el device flow no está disponible).

arc login --token eyJhbGciOiJIUzI1NiI...

La CLI valida el token mediante la API antes de guardarlo.

arc logout

Elimina las credenciales de ~/.arc/config.json y quita el bloque ARC de CLAUDE.md (si existe).

arc logout

arc projects

Lista los proyectos disponibles en el servidor.

arc projects

Salida:

Available projects:

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

Inicio de sesión

arc <project> [mode]

Inicializa una sesión de Claude con el contexto completo del proyecto. Equivalente a arc start <project> [mode].

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

Qué ocurre al iniciar:

1. Petición GET /api/cli/init/:project/:mode — obtención de CLAUDE.md, worker config y skills
2. Session-start picker (issue #115) — selección interactiva del issue activo para la sesión: issues abiertos (orden P0→P3 + más recientes primero, filtro fuzzy si >10), recientemente cerrados (con reopen-confirm al seleccionar), [n] crear nuevo, [q] omitir con doble confirmación. El id seleccionado se guarda en ~/.arc/sessions/<project>-<worker>.json como active_issue_id
3. Inyección del contexto en el CLAUDE.md local (bloque ARC Cloud + bloque Active issue: #N — Title)
4. La variable de entorno ARC_ACTIVE_ISSUE_ID=<id> se pasa al subproceso de Claude — la herramienta Bash la detecta para arc issue log sin re-prompt
5. Limpieza de entradas obsoletas de .mcp.json (si las hay)
6. Inicio del subproceso claude con interactividad TTY
7. Inicio del watcher en background (ver "Monitoreo de sesiones")

Parámetros:

Bypass no interactivo: ARC_ISSUE_ID=42 arc my-project dev omite el picker y usa el id indicado (para CI/scripts).

Cambio mid-sesión: arc issue switch <id> (desde otra terminal) cambia el issue activo — escribe switched_away en el anterior y switched_in en el nuevo. La sesión actual tomará el nuevo id tras reiniciarse.

arc continue <project> [mode]

Retoma la última sesión de Claude Code (ventana de 24 horas). Restaura automáticamente active_issue_id sin re-prompt.

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

arc tour

Onboarding interactivo de 5 pasos en la terminal (refleja el checklist web). El progreso se sincroniza con el dashboard web.

arc tour

Gestión de issues

arc issues [--status <filter>]

Lista los issues del proyecto.

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

Salida:

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]

Crear un nuevo 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

Parámetros:

arc issue update <id> [options]

Actualizar un issue existente.

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"

Parámetros:

Se requiere al menos un parámetro para actualizar.

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

Añadir una entrada de progreso al issue (activity log).

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

Parámetros:

El backend (POST /api/mcp/issues/:project/:id/log) acepta los campos opcionales type (whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) y ts (ISO-8601 para entradas backdated; las futuras se clampean a now). Lo usa internamente el session-start picker (#115) y arc retro (#117).

arc issue switch <id>

Cambiar el issue activo para la sesión actual (issue #115). Guarda en ~/.arc/sessions/<project>-<worker>.json, escribe switched_away en el issue anterior y switched_in en el nuevo.

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

Validación: el issue debe existir y estar open. Si está cerrado, primero ejecuta arc issue update <id> --status open.

arc sessions <project> [mode]

Ver todas las sesiones guardadas de un proyecto y, si hace falta, restaurar cualquiera de ellas — incluso si olvidaste indicar continue (issue #131).

arc sessions arc-v2                    # todos los workers
arc sessions arc-v2 --worker developer # solo developer

Muestra una tabla: estado del transcript (● existe / ✗ perdido), nombre del worker, session-id corto, antigüedad de la sesión, issue activo. Debajo — la lista de todos los archivos .jsonl, incluidos los "huérfanos" (no vinculados al worker actual).

Tras la tabla — un picker interactivo:

• Escribe el nombre del worker (developer, sentinel…) — restaura la última sesión de ese worker
• Escribe 8 caracteres del session-id — restaura una sesión concreta
• Enter — omitir

Cómo funciona: el picker escribe el session_id + transcript_path elegidos en ~/.arc/sessions/<project>-<worker>.json y luego lanza el arc <project> continue habitual.

arc retro <project> [options]

Reconstruir issues retroactivamente a partir del historial de sesiones y del git log (issue #117). Escanea ~/.arc/sessions/<project>-*.json, lee el primer prompt del usuario en el transcript JSONL y recopila commits con 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

Qué se omite automáticamente:

Qué ocurre con --apply:

1. createIssue para cada candidato (priority=P2, label=retro)
2. Entradas de actividad backdated: session_start (started_at) + auto_summary por commit (timestamp del commit) + session_end (ended_at) — vía POST /log con campo ts
3. Sesiones de >30 días con commits → status=closed inmediatamente. Recientes sin terminar → status=open.

Skills y conocimiento

arc skill <name>

Cargar un skill desde Cloud. Muestra las instrucciones del skill y sus evals (si los hay).

arc skill consultant_system
arc skill crm-api-reference

Requiere la variable ARC_PROJECT (se establece automáticamente con arc start).

Si el skill no se encuentra, la CLI mostrará la lista de los disponibles.

arc kb search "<query>"

Búsqueda en la wiki del proyecto. Coincidencia por palabras clave en nombres de archivos; devuelve hasta 5 mejores resultados (el contenido se trunca a 2000 caracteres).

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

arc learnings

Reglas y correcciones acumuladas de todas las sesiones del proyecto.

arc learnings

Salida:

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

Wiki y Roadmap

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

Crear o actualizar una página de la wiki del proyecto.

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

Parámetros:

Salida: Wiki created: architecture.md (342 bytes) o Wiki updated: ...

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

Actualizar el estado de una fase en el roadmap del proyecto.

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

Parámetros:

Reportes

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

Enviar un reporte de sesión a 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"

Parámetros:

Documentation Enforcement (Phase 49.1-49.2.1)

ARC incluye un sistema integrado que mantiene la documentación actualizada sin recordatorios manuales. Funciona junto con el pre-push git hook (scripts/check-docs-coverage.ts).

arc wrapup

Checklist de solo lectura — muestra qué docs necesitan actualizarse para los commits sin publicar.

arc wrapup

Delega en scripts/check-docs-coverage.ts. Mapping:

arc wrapup --generate

Auto-genera entradas esqueleto para los docs faltantes. Escribe stubs marcados con TODO en:

• learnings.md — timestamp + scope detectado automáticamente (api/backend/frontend/infra/process)
• docs/ROADMAP.md — encabezado Phase NN + resumen del commit
• docs/status/current-state.json — version bump + cambio al inicio

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

Los marcadores TODO no pasarán la revisión a propósito — se genera la estructura, no el contenido.

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

Captura investigaciones, decisiones o hallazgos directamente en learnings.md sin necesidad de un commit de código. Cubre el punto ciego del trabajo sin commits de código (análisis de capacidad, comparación de brokers, revisión 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."

La CLI clasifica automáticamente:

• Tipo: decision / lesson / finding / spike (pistas por regex)
• Scope: infra / perf / security / api / frontend / process

Formato de entrada:

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

GitHub Integration (Phase 49.3)

Notificaciones basadas en webhooks + feed en la UI para repositorios GitHub enlazados.

arc github link <project> <owner/repo>

Enlazar un repositorio a un proyecto. Devuelve la URL del webhook, el secret e instrucciones paso a paso para GitHub repo Settings → Webhooks.

arc github link arc-v2 SerhiiInUa/citadel-v2

Salida:

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

Lista los repositorios enlazados al proyecto (por defecto: env ARC_PROJECT).

arc github links arc-v2

arc github unlink <project> <id>

Eliminar un enlace por id (obtenido con arc github links).

arc github unlink arc-v2 3

Eventos soportados: push, pull_request, workflow_run, issues (95% de los casos de uso).

Qué obtienes tras la configuración:

• Notificación por Telegram al propietario del proyecto en cada evento (ícono + resumen + enlace a GitHub)
• Feed en el sidebar del Workspace ContextRail (polling cada 30s, últimos 8 eventos)

Guía de configuración detallada: GitHub Integration Setup.

Memoria neuronal

arc memory refresh

Phase 71.8 (#365): re-embed de todas las fuentes de conocimiento clave del proyecto (MANIFEST + ROADMAP + wiki + issues abiertos) en el RAG store self-hosted (embeddings + embeddings_vec). El mismo endpoint, nueva semántica — escribe en la SQLite local, no en Google NotebookLM.

arc memory refresh

Salida:

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

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

Timeout: 30 segundos (volumen de llamadas de embed a Cohere para el re-embed completo).

Normalmente este paso no es necesario — los hooks de la Phase 71.5 re-embeben automáticamente cada escritura de wiki/issue/skill. arc memory refresh es útil como "force re-index" tras un pull masivo o una migración.

arc memory fetch-artifact — eliminado en Phase 71.8

El audio overview de NotebookLM no tiene equivalente en RAG. El endpoint devuelve 410 Gone. Si necesitas un resumen por voz — ver la futura Phase de Whisper TTS sobre la wiki del proyecto.

Variables de entorno

Se establecen automáticamente con arc start, pero pueden configurarse manualmente para usar subcomandos fuera de una sesión.

Ejemplo de uso manual (fuera de arc start):

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

Monitoreo de sesiones

Al ejecutar arc start, se inicia automáticamente un watcher en background que:

1. Detecta el nuevo archivo .jsonl en ~/.claude/projects/{normalized-cwd}/
2. Cada 3 segundos lee las nuevas líneas del transcript
3. Parsea los mensajes user y assistant
4. Los envía a POST /api/cli/chat-log/:project (fire-and-forget)
5. El contenido se trunca a 10.000 caracteres por mensaje

El watcher no es crítico — los errores se ignoran y la sesión continúa funcionando aunque el CRM no esté disponible.

Ejemplos de uso

Flujo de trabajo típico

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

Sincronización de memoria

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

Trabajo con varios proyectos

# Sesión para el primer proyecto
arc project-alpha dev

# En otra terminal — sesión para el segundo
arc project-beta dev --role clceo

Timeouts