Comandos CLI

Referência completa de todos os comandos, flags e exemplos de uso da CLI do SpecForge.

A CLI specforge é distribuída como o pacote npm @specforge/cli. Ela gerencia autenticação, configuração de projeto, membros de equipe, gates de revisão e scaffolding de agentes.


npm install -g @specforge/cli
# ou execute diretamente
npx @specforge/cli@latest <command>

Autenticação

Autentique com o SpecForge.


specforge login

Abre um fluxo de OAuth baseado em navegador e armazena credenciais em ~/.specforge/config.json.

Para ambientes headless (servidores remotos, CI):


specforge login --api-key sf_live_...

Credenciais são armazenadas em ~/.specforge/config.json:


{
  "apiKey": "sf_live_...",
  "userId": "user_abc123"
}

Setup de Projeto

specforge init

Inicializa o SpecForge no diretório atual. Cria arquivos de configuração, detecta ferramentas de código instaladas e gera arquivos de agentes/skills.


specforge init

O Que Faz

Busca seus projetos da API do SpecForge e solicita seleção
Busca especificações do projeto selecionado e solicita seleção
Solicita formato de output — json (respostas MCP estruturadas) ou toon (legível por humanos)
Cria .specforge/config.json com IDs de projeto e especificação
Detecta ferramentas instaladas — Claude Code, Cursor, Gemini CLI, Codex CLI, OpenCode — e gera arquivos de configuração por ferramenta
Gera arquivos de instrução de agente — CLAUDE.md, GEMINI.md ou AGENTS.md dependendo das ferramentas detectadas
Opcionalmente configura Agent Teams — se CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 está definido, gera arquivos de skill em .claude/skills/

Flags

Flag	Efeito
`--project <id>`	Pular seleção de projeto, usar este ID de projeto
`--spec <id>`	Pular seleção de especificação, usar este ID de especificação
`--format <type>`	Definir formato de output: `json` ou `toon`
`--yes`	Aceitar todos os padrões sem solicitar
`--force`	Sobrescrever arquivos de configuração existentes sem confirmação
`--spec-only`	Atualizar apenas o ID da especificação, manter todo o resto
`--show`	Imprimir configuração gerada no stdout ao invés de escrever arquivos
`--skip-git`	Pular verificações de repositório git durante o init
`--no-agents`	Pular geração de arquivos de instrução de agente


# Não-interativo para CI
specforge init --project proj_abc123 --spec spec_xyz789 --format json --yes
 
# Atualizar apenas a especificação ativa
specforge init --spec-only
 
# Pré-visualizar o que seria gerado
specforge init --show
 
# Reinicializar, sobrescrevendo arquivos existentes
specforge init --force

ℹ️ Se arquivos de configuração já existem, o specforge init solicita confirmação antes de sobrescrever, a menos que --force seja passado.

specforge configure

Visualize ou defina valores de configuração. Sem argumentos, mostra a configuração completa resolvida. Com uma chave, mostra aquele valor. Com chave e valor, define.


specforge configure [key] [value]

Suporta caminhos aninhados com notação de ponto:


# Ver toda a configuração
specforge configure
 
# Ver um valor específico
specforge configure defaultProjectId
 
# Definir um valor
specforge configure format json
 
# Definir valores aninhados
specforge configure agentTeams.enabled true
specforge configure agentTeams.strategy wave
specforge configure agentTeams.maxParallelEpics 3
 
# Definir valores de config de review
specforge configure reviewConfig.readinessThreshold 85
specforge configure reviewConfig.gates.git_evidence false
specforge configure reviewConfig.testEvidence verbose

Modifica .specforge/config.json diretamente. Útil para scripting ou fazer mudanças pontuais sem re-executar o init.

specforge switch

Muda o contexto ativo de projeto ou especificação.


specforge switch <id>

O <id> pode ser um ID de projeto ou de especificação. O SpecForge detecta o tipo automaticamente.


# Mudar para um projeto diferente
specforge switch proj_abc123
 
# Mudar para uma especificação diferente
specforge switch spec_xyz789
 
# Mudar ambos de uma vez
specforge switch proj_abc123 --spec spec_xyz789

Atualiza .specforge/config.json e regenera arquivos de instrução de agente para refletir o novo contexto. O servidor MCP pega a mudança na próxima chamada de ferramenta.

Diagnósticos

specforge doctor

Execute diagnósticos para verificar sua configuração do SpecForge. Verifica autenticação, configuração do projeto, conectividade do servidor MCP e setup de agente.


specforge doctor

Flag	Efeito
`--json`	Saída dos resultados como JSON
`--verbose`	Mostrar informações diagnósticas detalhadas incluindo tempos de resposta da API


SpecForge Doctor
  API Key         ✓ authenticated as user@example.com
  MCP Server      ✓ registered in .mcp.json
  Project         ✓ proj_abc123 accessible
  Specification   ✓ spec_xyz789 loaded (3 epics, 14 tickets)
  Agent Config    ✓ CLAUDE.md present
  Git             ✓ clean working tree

All checks passed.

✅ Execute specforge doctor após qualquer mudança de configuração para verificar se tudo ainda funciona.

specforge status

Exiba o contexto de trabalho atual: projeto ativo, especificação e resumo de status de tickets.


specforge status

Flag	Efeito
`--json`	Saída como JSON
`--toon`	Exibir um resumo visual com barras de progresso e contagens de tickets

Planejamento & Revisão

specforge plan

Pré-visualize o plano de implementação para a especificação ativa. Mostra ordenação de tickets, waves e esforço estimado sem iniciar nenhum trabalho.


specforge plan

Flag	Efeito
`--strategy <strategy>`	Estratégia de planejamento a pré-visualizar
`--spec <id>`	ID da especificação (padrão é a spec ativa)
`--json`	Saída como JSON


specforge plan --strategy parallel --json

specforge review-planning

Execute o gate de Planning Review para uma especificação. Avalia prontidão, completude e qualidade estrutural.


specforge review-planning [specId]

Se nenhum specId é fornecido, usa a especificação ativa.

Flag	Efeito
`--json`	Saída dos resultados como JSON
`--toon`	Exibir um resumo visual do review

specforge review-implementation

Execute o gate de Implementation Review para uma especificação. Avalia trabalho completado contra padrões de qualidade.


specforge review-implementation [specId]

Flag	Efeito
`--json`	Saída dos resultados como JSON
`--toon`	Exibir um resumo visual do review

Gestão de Especificação

specforge spec activate

Define uma especificação como o contexto ativo para o projeto atual.


specforge spec activate <spec-id>

specforge spec deactivate

Limpa o contexto de especificação ativa.


specforge spec deactivate

Gestão de Equipe

specforge members add

Convide um usuário para o projeto atual.


specforge members add <email> [--role <role>]

Papéis: admin, member, viewer. Padrão é member.


specforge members add alice@example.com
specforge members add bob@example.com --role admin

specforge members role

Altere o papel de um membro.


specforge members role <email> <role>

specforge members remove

Remova um membro do projeto.


specforge members remove <email>

⚠️ Remover um membro revoga o acesso imediatamente e não pode ser desfeito — você deve re-convidar para restaurar o acesso.

specforge invitations accept

Aceite um convite de projeto.


specforge invitations accept <invitation-id>

specforge invitations decline

Recuse um convite de projeto.


specforge invitations decline <invitation-id>

Scaffolding de Agente

specforge scaffold

Gere ou regenere arquivos de configuração de agente para ferramentas de código detectadas. Use quando adicionar uma nova ferramenta ao seu ambiente ou resetar uma configuração que você acidentalmente modificou.


specforge scaffold

Flag	Efeito
`--target <target>`	Ferramenta específica: `claude-code`, `cursor`, `gemini`, `codex`, `opencode`
`--dry-run`	Pré-visualizar o que seria gerado sem escrever arquivos


# Detectar todas as ferramentas e gerar configs
specforge scaffold
 
# Mirar uma ferramenta específica
specforge scaffold --target claude-code
 
# Pré-visualizar sem escrever
specforge scaffold --dry-run

Arquivos Gerados por Alvo

Alvo	Arquivos Gerados
`claude-code`	`.mcp.json`, `CLAUDE.md`, `.claude/skills/`, `.claude/agents/`
`cursor`	`.mcp.json`, `AGENTS.md`
`gemini`	`.gemini/settings.json`, `GEMINI.md`
`codex`	`.codex/config.toml`, `AGENTS.md`
`opencode`	`opencode.json`, `AGENTS.md`

Feedback

specforge feedback

Submeta feedback sobre o SpecForge diretamente pela CLI.


specforge feedback

Abre um prompt interativo para categorizar e descrever seu feedback.

Resumo de Arquivos

Arquivo	Escopo	Propósito
`~/.specforge/config.json`	Global	Chave de API e credenciais da conta
`.specforge/config.json`	Projeto	ID do projeto, ID da especificação, configuração de Agent Teams
`.mcp.json`	Projeto	Registro de servidor MCP para Claude Code e Cursor
`CLAUDE.md`	Projeto	Âncora de contexto do projeto para Claude Code
`GEMINI.md`	Projeto	Instruções de agente para Gemini CLI
`AGENTS.md`	Projeto	Instruções universais de agente para Codex CLI, OpenCode e outros
`.claude/skills/`	Projeto	Skills operacionais para Claude Code (planejamento, implementação, validação)
`.claude/agents/`	Projeto	Definições de agente para Agent Teams do Claude Code
`.gemini/settings.json`	Projeto	Configuração MCP para Gemini CLI
`.codex/config.toml`	Projeto	Configuração MCP para Codex CLI
`opencode.json`	Projeto	Configuração MCP para OpenCode

ℹ️ Adicione .specforge/ ao seu .gitignore se sua configuração contém valores sensíveis. O arquivo .mcp.json é seguro para commitar desde que você use variáveis de ambiente para a chave de API ao invés de hardcode.

Veja Também

Schema de Configuração — Schema completo de todos os arquivos de configuração
Ferramentas MCP — As 22 ferramentas que esses comandos configuram acesso
Instalar CLI — Walkthrough de setup inicial