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 solve | Compute a deterministic read-only schedule. |
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 bundled local read-only preview. |
planq show | Start a foreground bundled local preview without session discovery. |
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
--checkwhen 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_ORIGINcan 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.txtDev
Usage: planq dev [<entry>...] [--local | --site <https-url>] [--no-open]
Options
| Option | Required | Value |
|---|---|---|
--local | No | Use the bundled workbench and override PLAN_SITE. |
--site | No | https-url |
--force-site | No | Skip site protocol probing; select planq.dev if no site is configured. |
--no-open | No | Do not launch the browser. |
--port | No | 1..65535 |
--now | No | YYYY-MM-DD |
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Invalid plan, operation, or source baseline |
2 | Argument or file access error |
3 | Unexpected internal error |
Notes
- The default workbench is bundled with the CLI and does not probe the hosted site.
--localoverridesPLAN_SITE; it conflicts with--siteand--force-site.--siteoverridesPLAN_SITE. Non-emptyPLAN_SITEselects an HTTPS site; an empty value selects local preview.- Site protocol mismatch or probe failure falls back to valid bundled assets.
--force-siteskips this check and selects planq.dev when no site is configured. - Saved sources stay local. Stop with Ctrl+C;
planq openreuses the latest dev session.
Examples
planq dev project.plan
planq dev project.plan --local
planq dev project.plan --site https://planq.devFormat
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.
--stdinnever writes the source path.
Examples
planq format project.plan
planq format --stdin --source-path /repo/project.planInit
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;
--afterremains a dependency.
Examples
planq milestone list project.plan --order file
planq milestone get project.plan release-readyOpen
Usage: planq open [--scale day|week|month] [--focus <task-id>]
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Invalid plan, operation, or source baseline |
2 | Argument or file access error |
3 | Unexpected internal error |
Notes
- Validates and reopens the recorded local or site dev session; it does not start another server or probe the site.
- Restart dev if its temporary discovery record is stale or from an older implementation.
Examples
planq open
planq open --scale monthProject
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
.planfiles are not scanned.
Examples
planq project validate
planq project validate --project products/releaseResources
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
syncshows a diff by default. Only--acceptatomically updatesresources.lock.json.
Examples
planq resources init
planq resources format
planq resources status --offline
planq resources sync
planq resources sync --acceptShow
Usage: planq show <entry>... [--local | --site <https-url>] [--scale day|week|month] [--focus <task-id>]
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Invalid plan, operation, or source baseline |
2 | Argument or file access error |
3 | Unexpected internal error |
Notes
- Uses the same local default, preview options and foreground lifecycle as dev, with explicit entries.
- Supports
--local,--site,--force-site,--no-open,--portand--now; does not create session discovery state for open.
Examples
planq show project.plan --scale week
planq show project.plan --local --focus releaseSkill
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/planq/under the Git root. - The fixed
result.integrationsorder 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--forcemode, and PlanQ never creates.codex/skillsor a user-Home Skill.
Examples
planq skill status
planq skill install --project products/releaseSolve
Usage: planq solve <entry> [--now YYYY-MM-DD]
Positionals
| Name | Required |
|---|---|
entry | Yes |
Options
| Option | Required | Value |
|---|---|---|
--now | No | YYYY-MM-DD |
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Invalid plan, operation, or source baseline |
2 | Argument or file access error |
3 | Unexpected internal error |
Notes
--nowoverrides the entry:now; otherwise PlanQ uses the project-timezone session date.- Computed dates are returned in the SolveResult and may be cached under
.plan/solve/; they are never written to source. - Dependencies, deadlines, and person capacity are hard constraints. Failed results contain no partial schedule.
Examples
planq solve release.plan
planq solve release.plan --now 2026-10-05Task
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
--afteraccepts a work-item name or@id;--toaccepts only a project@person-key.- Placement controls sibling order and is separate from dependency order.
--effort <N>pdsets positive person-day effort with at most four decimal places;task update --clear effortremoves it.- Effort is mutually exclusive with explicit start/end. Switch modes atomically by setting one and clearing the other in the same update.
Examples
planq task list project.plan --order file
planq task add project.plan --id brd --name BRD --before prd
planq task add project.plan --id implementation --name Implementation --effort 3.5pd
planq task update project.plan implementation --effort 2pd --clear start --clear end
planq task update project.plan brd --firstFor commands without a dedicated section, run planq <command> --help and consume the returned versioned JSON help envelope.