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 e scaffolding de agentes.

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

Autenticação

specforge login

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

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

Flags

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

O configure aceita exatamente cinco chaves planas (sem caminhos com ponto). Qualquer outra coisa é rejeitada com um erro de “chave inválida”:

# Ver toda a configuração
specforge configure
 
# Ver um valor específico
specforge configure defaultProjectId
 
# Definir o formato de output do MCP local (json ou toon)
specforge configure mcpOutputFormat json
 
# Definir o projeto / especificação padrão
specforge configure projectId proj_abc123
specforge configure specificationId spec_xyz789

Modifica .specforge/config.json (chaves de projeto) ou ~/.specforge/config.json (chaves globais) diretamente. Útil para scripting ou fazer mudanças pontuais sem re-executar o init.

ℹ️ Configurações do Agent Teams (agentTeams.*) e outras seções estruturadas não são chaves do configure — elas vivem no arquivo .specforge/config.json e são definidas pelo specforge init ou editando esse arquivo à mão. Veja o Schema de Configuração.

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

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

Diagnóstico & Debug

specforge debug

Diagnósticos de baixo nível para inspecionar a superfície MCP e a conectividade. Útil ao investigar uma integração de agente.

specforge debug call <tool>    # Dispatch direto de ferramenta MCP
specforge debug tools          # Listar ferramentas MCP disponíveis
specforge debug test           # Teste de conexão
specforge debug whoami         # Identidade e informações de config

ℹ️ O gate de planning-review e o assay por ticket rodam dentro das ferramentas MCP (complete_planning_session, complete_work_session) — não existe um comando specforge de revisão autônomo. Veja Ferramentas MCP.

Gestão de Equipe

specforge members add

Convide um usuário para o projeto atual.

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

Papéis: editor, viewer. Padrão é editor. (O criador do projeto é o owner; convites aceitam apenas editor ou viewer.)

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

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

# 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

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

ℹ️ 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 17 ferramentas que esses comandos configuram acesso
• Instalar CLI — Walkthrough de setup inicial