Referencia de la CLI

La CLI de Planu (planu) te permite gestionar Planu desde tu terminal — instalarla en herramientas de IA, validar specs, ejecutar auditorías y mucho más.

Inicio rápido

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

# Ou sans installation globale
npx @planu/cli@latest <command>

Comandos

planu install

Detecta las herramientas de IA instaladas (Claude Code, Cursor, Windsurf, Zed, Cline, Continue) y añade la entrada MCP de Planu en sus archivos de configuración.

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

Flag	Descripción
--scope user|project	Instalar a nivel de usuario (global) o de proyecto. Pregunta si se omite.
--all	Omitir el menú de selección de herramienta e instalar en todas las detectadas.

# instalación interactiva
planu install

# instalar en todas las herramientas detectadas a nivel de usuario, sin interacción
planu install --scope user --all

planu doctor

Revisa todas las rutas de configuración conocidas de cada herramienta de IA e informa si la entrada MCP de Planu está presente, ausente o rota.

planu doctor

Ejemplo de salida:

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

Encuentra todos los archivos de configuración que contienen una entrada MCP de Planu y la elimina tras confirmación.

planu uninstall [--yes]

Flag	Descripción
--yes / -y	Omitir la confirmación interactiva (útil en scripts).

planu status

Actualiza el estado de una spec (por ejemplo, de draft a approved).

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

Flag	Descripción
--set / -s	Nuevo estado: draft, review, approved, implementing, done, blocked.
--notes / -n	Notas de revisión opcionales asociadas a la transición.
--project-id	ID del proyecto. Se detecta automáticamente del directorio actual si se omite.

planu status SPEC-042 --set approved
planu status SPEC-042 --set done --notes "Todos los criterios verificados"

planu validate

Valida una spec contra su código fuente — comprueba qué criterios de aceptación están cubiertos e informa la cobertura total.

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

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

planu audit

Ejecuta una auditoría de calidad de código en el proyecto y lo puntúa de 0 a 100 según principios SOLID, código limpio y cumplimiento de arquitectura.

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

Flag	Descripción
--path / -p	Directorio a auditar. Por defecto, el directorio actual.
--spec / -s	Limitar la auditoría a una spec específica.
--project-id	ID del proyecto. Se detecta automáticamente si se omite.

planu estimate

Estima el esfuerzo de implementación de una spec — horas, complejidad y desglose de costos.

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

planu estimate SPEC-042

planu create

Crea una nueva spec con título y metadatos opcionales.

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

Flag	Descripción
--type / -t	Tipo de spec: feature, fix, chore, spike.
--description / -d	Descripción corta. Por defecto usa el título si se omite.
--path / -p	Directorio del proyecto. Por defecto, el directorio actual.
--scope	Alcance de la spec.
--target	Capa o módulo objetivo.
--feature	Grupo de funcionalidad padre.

planu create "Agregar login con OAuth" --type feature
planu create "Corregir puntero nulo en checkout" --type fix --description "Puntero nulo cuando el carrito está vacío"

planu list

Lista todas las specs del proyecto actual, con filtro opcional por estado o tipo.

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

Flag	Descripción
--status / -s	Filtrar por estado: draft, review, approved, implementing, done, blocked.
--type / -t	Filtrar por tipo: feature, fix, chore, spike.
--project-id	ID del proyecto. Se detecta automáticamente si se omite.

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

planu init

Inicializa un directorio como proyecto Planu — escanea el stack tecnológico, configura el idioma y crea los metadatos del proyecto.

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

Flag	Descripción
--locale / -l	Idioma para el contenido de las specs: en, es, pt, fr, de, zh.
--rate / -r	Tarifa horaria en USD para estimaciones de costo.
--level	Nivel de experiencia: junior, mid, senior.
--profile	Perfil de usuario: developer, product-owner, designer, non-technical.

planu init
planu init /ruta/al/proyecto --locale es --rate 80

planu serve

Inicia el servidor MCP de Planu con transporte HTTP en lugar de stdio. Útil para clientes remotos o basados en navegador.

planu serve [--port 3100]

planu serve --port 8080

planu dashboard

Abre el panel web de Planu — una interfaz local en el navegador para explorar specs, métricas e informes.

planu dashboard [--port 5050]

planu dashboard
planu dashboard --port 9000

planu watch

Observa un directorio de proyecto en busca de cambios en archivos y dispara los manejadores de hooks configurados (on-save, on-create, on-delete).

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

Flag	Descripción
--hooks / -H	Tipos de hook separados por comas a observar. Por defecto: on-save,on-create,on-delete.
--verbose / -V	Mostrar registros detallados de ejecución de hooks.
--dry-run	Previsualizar qué hooks se dispararían sin ejecutarlos.

planu watch
planu watch /ruta/al/proyecto --hooks on-save --verbose
planu watch --dry-run

planu handoff

Genera un prompt estructurado de handoff para que un agente de IA implemente una spec de forma autónoma.

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

Flag	Descripción
--name / -n	Nombre del agente. Por defecto: Agent-1.
--role / -r	Rol del agente: implementer, reviewer, tester. Por defecto: implementer.
--files / -f	Lista de archivos separados por comas asignados a este agente.
--project-id	ID del proyecto. Se detecta automáticamente si se omite.

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

Flujos de trabajo habituales

Instalar en todos los hosts detectados

planu install --global

Modo headless para CI/CD

Usa los mismos comandos locales sin restricciones en CI; no se requiere una credencial comercial de Planu.

planu validate SPEC-042
planu audit --path /ruta/al/proyecto

Ciclo SDD completo desde la terminal

planu init                                   # inicializar proyecto
planu create "Agregar flujo de pago" --type feature
planu list --status draft                    # revisar specs pendientes
planu status SPEC-001 --set approved
planu validate SPEC-001                      # verificar cobertura tras implementar
planu audit                                  # puntuar calidad del código

Flags globales

Estos flags aplican a todos los comandos.

Flag	Corto	Descripción
--help	-h	Mostrar ayuda para el comando actual.
--version		Mostrar la versión de Planu instalada.
--json		Salida en JSON sin formato (útil para scripting y pipes).
--quiet	-q	Suprimir la salida no esencial.
--verbose		Incluir el stack trace completo en errores.