ARC CLI — Referência de comandos

ARC CLI é a ferramenta de linha de comando para interagir com o Arc Cloud. Gerencie projetos, issues, wiki e skills diretamente do terminal.

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

Instalação e configuração

A configuração é salva em ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

Autenticação via device code flow. Abre o navegador para confirmação.

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

Após executar, o CLI exibe uma URL e um código de uso único. Abra a URL no navegador, confirme a autorização — o CLI receberá o token automaticamente.

arc login --token <token>

Autenticação direta por token (para automação ou quando o device flow não está disponível).

arc login --token eyJhbGciOiJIUzI1NiI...

O CLI valida o token via API antes de salvar.

arc logout

Remove as credenciais de ~/.arc/config.json e limpa o bloco ARC do CLAUDE.md (se existir).

arc logout

arc projects

Lista os projetos disponíveis no servidor.

arc projects

Saída:

Available projects:

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

Iniciando uma sessão

arc <project> [mode]

Inicializa uma sessão Claude com o contexto completo do projeto. Equivalente a arc start <project> [mode].

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

O que acontece ao iniciar:

1. Requisição GET /api/cli/init/:project/:mode — obtém CLAUDE.md, configuração de workers e skills
2. Session-start picker (issue #115) — seleção interativa do issue ativo para a sessão: issues abertas (ordenadas P0→P3 + mais recentes primeiro, filtro fuzzy se >10), fechadas recentemente (com confirmação de reabertura ao selecionar), [n] criar novo, [q] pular com confirmação dupla. O id selecionado é salvo em ~/.arc/sessions/<project>-<worker>.json como active_issue_id
3. Injeção de contexto no CLAUDE.md local (bloco ARC Cloud + bloco Active issue: #N — Title)
4. A variável de ambiente ARC_ACTIVE_ISSUE_ID=<id> é passada para o subprocess Claude — a ferramenta Bash a enxerga para arc issue log sem re-prompt
5. Limpeza de entradas depreciadas do .mcp.json (se houver)
6. Inicialização do subprocess claude com interatividade TTY
7. Início do watcher em background (veja "Monitoramento de sessões")

Parâmetros:

Bypass não interativo: ARC_ISSUE_ID=42 arc my-project dev pula o picker e usa o id informado (para CI/scripts).

Troca durante a sessão: arc issue switch <id> (em um terminal paralelo) altera o issue ativo — registra switched_away no anterior e switched_in no novo. A sessão atual usará o novo id após reiniciar.

arc continue <project> [mode]

Retoma a última sessão Claude Code (janela de 24 horas). Restaura automaticamente o active_issue_id sem re-prompt.

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

arc tour

Onboarding interativo de 5 etapas no terminal (espelha o checklist web). O progresso é sincronizado com o dashboard web.

arc tour

Gerenciamento de issues

arc issues [--status <filter>]

Lista as issues do projeto.

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

Saída:

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]

Crie uma nova 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]

Atualiza uma 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:

Pelo menos um parâmetro é necessário para atualizar.

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

Adiciona um registro de progresso à issue (log de atividade).

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

Parâmetros:

O backend (POST /api/mcp/issues/:project/:id/log) aceita os campos opcionais type (whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) e ts (ISO-8601 para entradas backdated; datas futuras são limitadas ao momento atual). Usado internamente pelo session-start picker (#115) e pelo arc retro (#117).

arc issue switch <id>

Altera o issue ativo da sessão atual (issue #115). Salva em ~/.arc/sessions/<project>-<worker>.json, registra switched_away na issue anterior e switched_in na nova.

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

Validação: a issue deve existir e estar open. Se estiver fechada, execute primeiro arc issue update <id> --status open.

arc retro <project> [options]

Reconstrói issues retroativamente a partir do histórico de sessões e do git log (issue #117). Escaneia ~/.arc/sessions/<project>-*.json, lê o primeiro prompt do usuário no transcript JSONL e coleta 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

O que é ignorado automaticamente:

O que acontece com --apply:

1. createIssue para cada candidato (priority=P2, label=retro)
2. Entradas de atividade backdated: session_start (started_at) + auto_summary por commit (timestamp do commit) + session_end (ended_at) — via POST /log com campo ts
3. Sessões com >30 dias e commits → status=closed imediatamente. Sessões recentes não finalizadas → status=open.

Skills e conhecimento

arc skill <name>

Carrega uma skill do Cloud. Exibe as instruções da skill e os evals (se houver).

arc skill consultant_system
arc skill crm-api-reference

Requer a variável ARC_PROJECT (definida automaticamente ao executar arc start).

Se a skill não for encontrada, o CLI exibe a lista das disponíveis.

arc kb search "<query>"

Pesquisa na wiki do projeto. Busca por palavras-chave nos nomes dos arquivos e retorna até 5 melhores resultados (conteúdo limitado a 2.000 caracteres).

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

arc learnings

Regras acumuladas e correções de todas as sessões do projeto.

arc learnings

Saída:

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

Wiki e Roadmap

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

Crie ou atualize uma página da wiki do projeto.

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

Parâmetros:

Saída: Wiki created: architecture.md (342 bytes) ou Wiki updated: ...

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

Atualiza o status de uma fase no roadmap do projeto.

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

Parâmetros:

Relatórios

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

Envia o relatório da sessão para o 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)

O ARC possui um sistema integrado que mantém a documentação atualizada sem precisar de lembretes manuais. Funciona em conjunto com o pre-push git hook (scripts/check-docs-coverage.ts).

arc wrapup

Checklist somente leitura — mostra quais docs precisam ser atualizados para commits ainda não enviados.

arc wrapup

Delega para scripts/check-docs-coverage.ts. Mapeamento:

arc wrapup --generate

Gera automaticamente entradas esqueleto para docs ausentes. Escreve stubs marcados com TODO em:

• learnings.md — timestamp + escopo detectado automaticamente (api/backend/frontend/infra/process)
• docs/ROADMAP.md — cabeçalho Phase NN + resumo do commit
• docs/status/current-state.json — bump de versão + alteração adicionada no início

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

Os marcadores TODO são intencionais e não passarão em revisão — o que é gerado é a estrutura, não o conteúdo.

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

Registra uma pesquisa, decisão ou descoberta diretamente no learnings.md sem precisar de um commit de código. Resolve o ponto cego de trabalho sem commits de código (análise de capacidade, comparação de brokers, avaliação 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."

O CLI classifica automaticamente:

• Tipo: decision / lesson / finding / spike (regex hints)
• Escopo: infra / perf / security / api / frontend / process

Formato da entrada:

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

Integração com GitHub (Phase 49.3)

Notificações via webhook e feed na UI para repositórios GitHub vinculados.

arc github link <project> <owner/repo>

Vincula um repositório ao projeto. Retorna a URL do webhook, o secret e instruções passo a passo para GitHub repo Settings → Webhooks.

arc github link arc-v2 SerhiiInUa/citadel-v2

Saída:

✓ 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 os repositórios vinculados ao projeto (padrão: variável de ambiente ARC_PROJECT).

arc github links arc-v2

arc github unlink <project> <id>

Remove um vínculo pelo id (obtido via arc github links).

arc github unlink arc-v2 3

Eventos suportados: push, pull_request, workflow_run, issues (95% dos casos de uso).

O que você ganha após a configuração:

• Notificação Telegram para o dono do projeto a cada evento (ícone + resumo + link do GitHub)
• Feed na barra lateral do Workspace ContextRail (polling a cada 30s, últimos 8 eventos)

Guia detalhado de configuração: GitHub Integration Setup.

Memória neural

arc memory refresh

Ressincronização completa de todas as fontes de conhecimento do projeto com o NotebookLM.

arc memory refresh

Saída:

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

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

Timeout: 30 segundos (aumentado devido ao volume de sincronização).

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

Baixa um artefato do NotebookLM (áudio de revisão etc.).

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

Timeout: 60 segundos.

Variáveis de ambiente

Definidas automaticamente ao executar arc start, mas podem ser configuradas manualmente para usar subcomandos fora de uma sessão.

Exemplo de uso manual (fora do arc start):

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

Monitoramento de sessões

Ao executar arc start, um watcher em background é iniciado automaticamente e:

1. Localiza o novo arquivo .jsonl em ~/.claude/projects/{normalized-cwd}/
2. A cada 3 segundos, lê as novas linhas do transcript
3. Faz o parse das mensagens user e assistant
4. As envia para POST /api/cli/chat-log/:project (fire-and-forget)
5. O conteúdo é limitado a 10.000 caracteres por mensagem

O watcher não é crítico — erros são ignorados e a sessão continua funcionando mesmo se o CRM estiver indisponível.

Exemplos de uso

Fluxo de trabalho 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"

Sincronização de memória

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

Trabalhando com múltiplos projetos

# Sessão para o primeiro projeto
arc project-alpha dev

# Em outro terminal — sessão para o segundo
arc project-beta dev --role clceo

Timeouts