CLI Reference

The planu CLI lets you manage Planu from your terminal — install it into AI tools, start the MCP server, validate specs, and more.

Quick start

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

# Or without a global install
npx @planu/cli@latest <command>

Commands

planu install

Detects installed AI tools (Claude Code, Cursor, Windsurf, OpenCode, Zed, Cline, Continue) and writes the Planu MCP entry to each config file. Use --codex to inject instructions into AGENTS.md for tools without MCP support.

planu install [--global] [--codex] [--cursor] [--project PATH]

Flag	Description
--global	Configure ALL detected AI tools in one command.
--codex	Inject Planu CLI instructions into AGENTS.md (for Codex / OpenAI).
--cursor	Configure Cursor specifically.
--project PATH	Project path for AGENTS.md injection. Defaults to current directory.

# Auto-configure every detected AI tool
planu install --global

# Inject into AGENTS.md only (for Codex)
planu install --codex

planu doctor

Checks every known AI tool config path and reports whether the Planu MCP entry is present, missing, or broken.

planu doctor

Example output:

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

Finds every config file that contains a Planu MCP entry and removes it after confirmation.

planu uninstall [--yes]

Flag	Description
--yes / -y	Skip the confirmation prompt (useful in scripts).

planu status

Updates the status of a spec (e.g. from draft to approved).

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

Flag	Description
--set / -s	New status: draft, review, approved, implementing, done, blocked.
--notes / -n	Optional review notes attached to the transition.
--project-id	Project ID. Auto-detected from the current directory if omitted.

planu status SPEC-042 --set approved
planu status SPEC-042 --set done --notes "All criteria verified"

planu validate

Validates a spec against its codebase — checks which acceptance criteria are covered and reports overall coverage.

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

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

planu audit

Runs a code quality audit on the project and scores it 0–100 for SOLID principles, clean code, and architecture compliance.

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

Flag	Description
--path / -p	Directory to audit. Defaults to the current directory.
--spec / -s	Limit audit to a specific spec.
--project-id	Project ID. Auto-detected if omitted.

planu estimate

Estimates implementation effort for a spec — hours, complexity, and cost breakdown.

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

planu estimate SPEC-042

planu create

Creates a new spec with a title and optional metadata.

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

Flag	Description
--type / -t	Spec type: feature, fix, chore, spike.
--description / -d	Short description. Defaults to the title if omitted.
--path / -p	Project directory. Defaults to the current directory.
--scope	Spec scope.
--target	Target layer or module.
--feature	Parent feature group.

planu create "Add OAuth login" --type feature
planu create "Fix null pointer on checkout" --type fix --description "Null pointer when cart is empty"

planu list

Lists all specs in the current project, optionally filtered by status or type.

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

Flag	Description
--status / -s	Filter by status: draft, review, approved, implementing, done, blocked.
--type / -t	Filter by type: feature, fix, chore, spike.
--project-id	Project ID. Auto-detected if omitted.

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

planu init

Initializes a directory as a Planu project — scans the stack, sets locale, and creates the project metadata.

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

Flag	Description
--locale / -l	Language for spec content: en, es, pt, fr, de, zh.
--rate / -r	Hourly rate in USD for cost estimates.
--level	Experience level: junior, mid, senior.
--profile	User profile: developer, product-owner, designer, non-technical.

planu init
planu init /path/to/project --locale es --rate 80

planu serve

Starts the Planu MCP server. By default uses stdio (for MCP clients like Claude Code, Cursor). Use --http to start an HTTP server compatible with OpenAI function calling.

planu serve [--http] [--port 7823]

Flag	Description
--http	Start HTTP server instead of MCP stdio.
--port	HTTP port. Default: 7823.

# MCP stdio mode (default — used by Claude Code, Cursor, Windsurf)
planu serve

# HTTP mode (for GPT-4, Gemini, Kimi, Claude API)
planu serve --http --port 7823
# Tools at: POST http://localhost:7823/v1/tools/call
# List at:  GET  http://localhost:7823/v1/tools

planu dashboard

Opens the Planu web dashboard — a local browser interface for browsing specs, metrics, and reports.

planu dashboard [--port 5050]

planu dashboard
planu dashboard --port 9000

planu watch

Watches a project directory for file changes and fires configured hook handlers (on-save, on-create, on-delete).

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

Flag	Description
--hooks / -H	Comma-separated hook types to watch. Default: on-save,on-create,on-delete.
--verbose / -V	Show detailed hook execution logs.
--dry-run	Preview which hooks would fire without executing them.

planu watch
planu watch /path/to/project --hooks on-save --verbose
planu watch --dry-run

planu handoff

Generates a structured handoff prompt for an AI agent to implement a spec autonomously.

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

Flag	Description
--name / -n	Agent name label. Default: Agent-1.
--role / -r	Agent role: implementer, reviewer, tester. Default: implementer.
--files / -f	Comma-separated list of files assigned to this agent.
--project-id	Project ID. Auto-detected if omitted.

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

Common workflows

Install in every detected host

planu install --global

CI/CD headless mode

Use the same unrestricted local commands in CI; no Planu entitlement credential is required.

planu validate SPEC-042
planu audit --path /path/to/project

Full SDD cycle from the terminal

planu init                                  # initialize project
planu create "Add payment flow" --type feature
planu list --status draft                   # review pending specs
planu status SPEC-001 --set approved
planu validate SPEC-001                     # check coverage after implementation
planu audit                                 # score code quality

Global flags

These flags apply to every command.

Flag	Short	Description
--help	-h	Show help for the current command.
--version		Show the installed Planu version.
--json		Output raw JSON (useful for scripting and piping).
--quiet	-q	Suppress non-essential output.
--verbose		Include full stack traces on errors.