Referência da CLI

A CLI do Planu (planu) permite gerenciar o Planu pelo terminal — instalar em ferramentas de IA, validar specs, executar auditorias e muito mais.

Início rápido

npm install -g @planu/cli
planu <command>

# Ou sem instalação global
npx @planu/cli@latest <command>

Comandos

planu install

Detecta as ferramentas de IA instaladas (Claude Code, Cursor, Windsurf, Zed, Cline, Continue) e adiciona a entrada MCP do Planu nos arquivos de configuração correspondentes.

planu install [--scope user|project] [--all]

Flag	Descrição
--scope user|project	Instalar no nível do usuário (global) ou do projeto. Pergunta se omitido.
--all	Ignorar o menu de seleção e instalar em todas as ferramentas detectadas.

# instalação interativa
planu install

# instalar em todas as ferramentas detectadas no escopo do usuário, sem interação
planu install --scope user --all

planu doctor

Verifica todos os caminhos de configuração conhecidos de cada ferramenta de IA e reporta se a entrada MCP do Planu está presente, ausente ou com problema.

planu doctor

Exemplo de saída:

Planu Doctor

  [+] Claude Code (user)    OK  ~/.claude.json
  [-] Cursor                not installed
  [?] Zed                   tool not found

Planu is installed in 1 location(s). Run `planu install` to add more.

planu uninstall

Encontra todos os arquivos de configuração que contêm uma entrada MCP do Planu e a remove após confirmação.

planu uninstall [--yes]

Flag	Descrição
--yes / -y	Ignorar a confirmação interativa (útil em scripts).

planu status

Atualiza o status de uma spec (por exemplo, de draft para approved).

planu status <specId> --set <status> [--project-id ID] [--notes "..."]

Flag	Descrição
--set / -s	Novo status: draft, review, approved, implementing, done, blocked.
--notes / -n	Notas de revisão opcionais associadas à transição.
--project-id	ID do projeto. Detectado automaticamente do diretório atual se omitido.

planu status SPEC-042 --set approved
planu status SPEC-042 --set done --notes "Todos os critérios verificados"

planu validate

Valida uma spec contra seu código-fonte — verifica quais critérios de aceitação estão cobertos e reporta a cobertura total.

planu validate <specId> [--project-id ID]

planu validate SPEC-042
planu validate SPEC-042 --project-id 1ef29aa7362bb087

planu audit

Executa uma auditoria de qualidade de código no projeto e atribui uma pontuação de 0 a 100 com base em princípios SOLID, código limpo e conformidade arquitetural.

planu audit [--path .] [--project-id ID] [--spec SPEC-001]

Flag	Descrição
--path / -p	Diretório a auditar. Padrão: diretório atual.
--spec / -s	Limitar a auditoria a uma spec específica.
--project-id	ID do projeto. Detectado automaticamente se omitido.

planu estimate

Estima o esforço de implementação de uma spec — horas, complexidade e detalhamento de custos.

planu estimate <specId> [--project-id ID]

planu estimate SPEC-042

planu create

Cria uma nova spec com título e metadados opcionais.

planu create <title> [--type feature] [--description "..."] [--path .]

Flag	Descrição
--type / -t	Tipo da spec: feature, fix, chore, spike.
--description / -d	Descrição curta. Usa o título se omitida.
--path / -p	Diretório do projeto. Padrão: diretório atual.
--scope	Escopo da spec.
--target	Camada ou módulo alvo.
--feature	Grupo de funcionalidade pai.

planu create "Adicionar login OAuth" --type feature
planu create "Corrigir ponteiro nulo no checkout" --type fix --description "Ponteiro nulo quando o carrinho está vazio"

planu list

Lista todas as specs do projeto atual, com filtro opcional por status ou tipo.

planu list [--status draft] [--type feature] [--project-id ID]

Flag	Descrição
--status / -s	Filtrar por status: draft, review, approved, implementing, done, blocked.
--type / -t	Filtrar por tipo: feature, fix, chore, spike.
--project-id	ID do projeto. Detectado automaticamente se omitido.

planu list
planu list --status approved
planu list --type fix --status done

planu init

Inicializa um diretório como projeto Planu — escaneia o stack tecnológico, define o idioma e cria os metadados do projeto.

planu init [path] [--locale en] [--rate 100] [--level junior|mid|senior] [--profile developer]

Flag	Descrição
--locale / -l	Idioma para o conteúdo das specs: en, es, pt, fr, de, zh.
--rate / -r	Taxa horária em USD para estimativas de custo.
--level	Nível de experiência: junior, mid, senior.
--profile	Perfil do usuário: developer, product-owner, designer, non-technical.

planu init
planu init /caminho/para/projeto --locale pt --rate 70

planu serve

Inicia o servidor MCP do Planu com transporte HTTP em vez de stdio. Útil para clientes remotos ou baseados em navegador.

planu serve [--port 3100]

planu serve --port 8080

planu dashboard

Abre o painel web do Planu — uma interface local no navegador para navegar por specs, métricas e relatórios.

planu dashboard [--port 5050]

planu dashboard
planu dashboard --port 9000

planu watch

Observa um diretório de projeto em busca de alterações em arquivos e dispara os handlers de hooks configurados (on-save, on-create, on-delete).

planu watch [path] [--hooks on-save,on-create] [--verbose] [--dry-run]

Flag	Descrição
--hooks / -H	Tipos de hook separados por vírgula. Padrão: on-save,on-create,on-delete.
--verbose / -V	Exibir logs detalhados de execução dos hooks.
--dry-run	Visualizar quais hooks seriam disparados sem executá-los.

planu watch
planu watch /caminho/para/projeto --hooks on-save --verbose
planu watch --dry-run

planu handoff

Gera um prompt estruturado de handoff para que um agente de IA implemente uma spec de forma autônoma.

planu handoff <specId> [--name Agent-1] [--role implementer] [--files src/a.ts,src/b.ts]

Flag	Descrição
--name / -n	Nome do agente. Padrão: Agent-1.
--role / -r	Papel do agente: implementer, reviewer, tester. Padrão: implementer.
--files / -f	Lista de arquivos separados por vírgula atribuídos a este agente.
--project-id	ID do projeto. Detectado automaticamente se omitido.

planu handoff SPEC-042
planu handoff SPEC-042 --name "Backend-Agent" --role implementer --files src/api/auth.ts,src/middleware/jwt.ts

Fluxos de trabalho comuns

Instalar em todos os hosts detectados

planu install --global

Modo headless para CI/CD

Use os mesmos comandos locais sem restrições no CI; nenhuma credencial comercial do Planu é necessária.

planu validate SPEC-042
planu audit --path /caminho/para/projeto

Ciclo SDD completo pelo terminal

planu init                                   # inicializar projeto
planu create "Adicionar fluxo de pagamento" --type feature
planu list --status draft                    # revisar specs pendentes
planu status SPEC-001 --set approved
planu validate SPEC-001                      # verificar cobertura após implementação
planu audit                                  # pontuar qualidade do código

Flags globais

Estes flags se aplicam a todos os comandos.

Flag	Curto	Descrição
--help	-h	Exibir ajuda para o comando atual.
--version		Exibir a versão do Planu instalada.
--json		Saída em JSON bruto (útil para scripting e pipes).
--quiet	-q	Suprimir saída não essencial.
--verbose		Incluir stack trace completo nos erros.