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

Resincronización completa de todas las fuentes de conocimiento del proyecto con 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 (aumentado por el volumen de sincronización).

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

Descargar un artefacto de NotebookLM (resumen en audio, etc.).

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

Timeout: 60 segundos.

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