CLI reference

Root usage: planq <command> [options]

All short-lived commands emit one JSON object to stdout. Exit code 0 is success, 1 is an invalid plan or operation, 2 is an argument or file access failure, and 3 is an unexpected internal error.

Commands

Command	Purpose
planq version	Print product and protocol versions.
planq validate	Validate one Plan entry and return structured diagnostics.
planq normalize	Validate and emit deterministic normalized IR.
planq format	Write or check canonical Plan source formatting.
planq migrate	Explicitly migrate legacy references to @id syntax.
planq init	Create a minimal valid Plan without overwriting existing paths.
planq apply	Validate and atomically apply an edit-set.
planq task	Query or safely mutate tasks.
planq milestone	Query or safely mutate milestones.
planq connect	Connect one local project to an online Workspace.
planq resources	Initialize, format, inspect, and synchronize project resources.
planq skill	Inspect or install the project-scoped Agent Skill.
planq project	Validate a manifest and all declared entries.
planq dev	Start a persistent live read-only preview.
planq show	Start an explicit one-session preview.
planq open	Reopen the most recent running preview session.
planq lsp	Start the stdio language server.

Apply

Usage: planq apply <file> --input <path|-> [--check]

Positionals

Name	Required
file	Yes

Options

Option	Required	Value
--input	Yes	edit-set JSON path or - for stdin
--check	No	Preview canonicalProposal without writing.

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• The default mode validates and atomically commits the complete edit-set.
• Use --check when a canonical proposal must be reviewed before writing.

Examples

planq apply project.plan --input changes.json --check
planq apply project.plan --input -

Connect

Usage: planq connect [--project <dir>] [--workspace <id>] [--token-stdin]

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• The default hosted origin is https://planq.dev; PLAN_ORIGIN can select another trusted deployment.
• Connection data is written only beneath .plan/ and must not be committed.

Examples

planq connect
planq connect --workspace workspace-id
planq connect --token-stdin < token.txt

Format

Usage: planq format [--check] <file> | planq format --stdin [--source-path <absolute-plan-path>]

Positionals

Name	Required
file	No

Options

Option	Required	Value
--check	No	Check canonical formatting without writing.
--stdin	No	Read from standard input without writing.
--source-path	No	absolute .plan path

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• Formatting is deterministic and does not infer or repair business meaning.
• --stdin never writes the source path.

Examples

planq format project.plan
planq format --stdin --source-path /repo/project.plan

Init

Usage: planq init <file> [--id <id>] [--name <name>]

Positionals

Name	Required
file	Yes

Options

Option	Required	Value
--id	No	bare identifier
--name	No	non-empty string

Exit codes

Code	Meaning
0	Success
2	Argument or file access error

Notes

• The file basename can provide the Plan ID only when it is already a valid bare identifier.

Examples

planq init demo.plan
planq init project.plan --id crm --name "CRM system"

Milestone

Usage: planq milestone <list|get|add|update|delete> ...

Subcommand	Usage
list	planq milestone list <file> [--order file] [--name <text>] [--parent <id>]
get	planq milestone get <file> <milestone-id>
add	planq milestone add <file> --id <id> --name <name> [milestone fields] [placement]
update	planq milestone update <file> <milestone-id> [milestone fields] [placement]
delete	planq milestone delete <file> <milestone-id>

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• Placement controls sibling order; --after remains a dependency.

Examples

planq milestone list project.plan --order file
planq milestone get project.plan release-ready

Project

Usage: planq project validate [--project <dir>]

Subcommand	Usage
validate	planq project validate [--project <dir>]

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• Only manifest-declared entries are validated; unrelated .plan files are not scanned.

Examples

planq project validate
planq project validate --project products/release

Resources

Usage: planq resources <init|format|status|sync> [options]

Subcommand	Usage
init	planq resources init [--project <dir>]
format	planq resources format [--project <dir>|--stdin]
status	planq resources status [--project <dir>] [--offline]
sync	planq resources sync [--project <dir>] [--accept]

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• sync shows a diff by default. Only --accept atomically updates resources.lock.json.

Examples

planq resources init
planq resources format
planq resources status --offline
planq resources sync
planq resources sync --accept

Skill

Usage: planq skill <status|install> [--project <dir>]

Subcommand	Usage
status	planq skill status [--project <dir>]
install	planq skill install [--project <dir>]

Exit codes

Code	Meaning
0	Success
2	Argument or file access error

Notes

• The canonical payload is .agents/skills/plan-gantt/ under the Git root.
• The fixed result.integrations order is Codex, Claude Code, then TRAE; each entry reports its project path, status, discovery mode, and relative conflicts.
• Installation atomically fills missing canonical and project discovery entries, and refuses different versions, local modifications, and unknown files.
• There is no --global, --agent, or --force mode, and PlanQ never creates .codex/skills or a user-Home Skill.

Examples

planq skill status
planq skill install --project products/release

Task

Usage: planq task <list|get|add|update|delete> ...

Subcommand	Usage
list	planq task list <file> [--order file] [--name <text>] [--parent <id>]
get	planq task get <file> <task-id>
add	planq task add <file> --id <id> --name <name> [task fields] [placement]
update	planq task update <file> <task-id> [task fields] [placement]
delete	planq task delete <file> <task-id>

Exit codes

Code	Meaning
0	Success
1	Invalid plan, operation, or source baseline
2	Argument or file access error

Notes

• --after accepts a work-item name or @id; --to accepts only a project @person-key.
• Placement controls sibling order and is separate from dependency order.

Examples

planq task list project.plan --order file
planq task add project.plan --id brd --name BRD --before prd
planq task update project.plan brd --first

For commands without a dedicated section, run planq <command> --help and consume the returned versioned JSON help envelope.