Skip to content

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 ​

CommandPurpose
planq versionPrint product and protocol versions.
planq validateValidate one Plan entry and return structured diagnostics.
planq normalizeValidate and emit deterministic normalized IR.
planq solveCompute a deterministic read-only schedule.
planq formatWrite or check canonical Plan source formatting.
planq migrateExplicitly migrate legacy references to @id syntax.
planq initCreate a minimal valid Plan without overwriting existing paths.
planq applyValidate and atomically apply an edit-set.
planq taskQuery or safely mutate tasks.
planq milestoneQuery or safely mutate milestones.
planq connectConnect one local project to an online Workspace.
planq resourcesInitialize, format, inspect, and synchronize project resources.
planq skillInspect or install the project-scoped Agent Skill.
planq projectValidate a manifest and all declared entries.
planq devStart a persistent bundled local read-only preview.
planq showStart a foreground bundled local preview without session discovery.
planq openReopen the most recent running preview session.
planq lspStart the stdio language server.

Apply ​

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

Positionals ​

NameRequired
fileYes

Options ​

OptionRequiredValue
--inputYesedit-set JSON path or - for stdin
--checkNoPreview canonicalProposal without writing.

Exit codes ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument 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 ​

bash
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 ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument 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 ​

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

Dev ​

Usage: planq dev [<entry>...] [--local | --site <https-url>] [--no-open]

Options ​

OptionRequiredValue
--localNoUse the bundled workbench and override PLAN_SITE.
--siteNohttps-url
--force-siteNoSkip site protocol probing; select planq.dev if no site is configured.
--no-openNoDo not launch the browser.
--portNo1..65535
--nowNoYYYY-MM-DD

Exit codes ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument or file access error
3Unexpected internal error

Notes ​

  • The default workbench is bundled with the CLI and does not probe the hosted site.
  • --local overrides PLAN_SITE; it conflicts with --site and --force-site.
  • --site overrides PLAN_SITE. Non-empty PLAN_SITE selects an HTTPS site; an empty value selects local preview.
  • Site protocol mismatch or probe failure falls back to valid bundled assets. --force-site skips this check and selects planq.dev when no site is configured.
  • Saved sources stay local. Stop with Ctrl+C; planq open reuses the latest dev session.

Examples ​

bash
planq dev project.plan
planq dev project.plan --local
planq dev project.plan --site https://planq.dev

Format ​

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

Positionals ​

NameRequired
fileNo

Options ​

OptionRequiredValue
--checkNoCheck canonical formatting without writing.
--stdinNoRead from standard input without writing.
--source-pathNoabsolute .plan path

Exit codes ​

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

Notes ​

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

Examples ​

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

Init ​

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

Positionals ​

NameRequired
fileYes

Options ​

OptionRequiredValue
--idNobare identifier
--nameNonon-empty string

Exit codes ​

CodeMeaning
0Success
2Argument or file access error

Notes ​

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

Examples ​

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

Milestone ​

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

SubcommandUsage
listplanq milestone list <file> [--order file] [--name <text>] [--parent <id>]
getplanq milestone get <file> <milestone-id>
addplanq milestone add <file> --id <id> --name <name> [milestone fields] [placement]
updateplanq milestone update <file> <milestone-id> [milestone fields] [placement]
deleteplanq milestone delete <file> <milestone-id>

Exit codes ​

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

Notes ​

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

Examples ​

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

Open ​

Usage: planq open [--scale day|week|month] [--focus <task-id>]

Exit codes ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument or file access error
3Unexpected 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 ​

bash
planq open
planq open --scale month

Project ​

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

SubcommandUsage
validateplanq project validate [--project <dir>]

Exit codes ​

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

Notes ​

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

Examples ​

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

Resources ​

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

SubcommandUsage
initplanq resources init [--project <dir>]
formatplanq resources format [--project <dir>|--stdin]
statusplanq resources status [--project <dir>] [--offline]
syncplanq resources sync [--project <dir>] [--accept]

Exit codes ​

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

Notes ​

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

Examples ​

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

Show ​

Usage: planq show <entry>... [--local | --site <https-url>] [--scale day|week|month] [--focus <task-id>]

Exit codes ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument or file access error
3Unexpected 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, --port and --now; does not create session discovery state for open.

Examples ​

bash
planq show project.plan --scale week
planq show project.plan --local --focus release

Skill ​

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

SubcommandUsage
statusplanq skill status [--project <dir>]
installplanq skill install [--project <dir>]

Exit codes ​

CodeMeaning
0Success
2Argument or file access error

Notes ​

  • The canonical payload is .agents/skills/planq/ 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 ​

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

Solve ​

Usage: planq solve <entry> [--now YYYY-MM-DD]

Positionals ​

NameRequired
entryYes

Options ​

OptionRequiredValue
--nowNoYYYY-MM-DD

Exit codes ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument or file access error
3Unexpected internal error

Notes ​

  • --now overrides 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 ​

bash
planq solve release.plan
planq solve release.plan --now 2026-10-05

Task ​

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

SubcommandUsage
listplanq task list <file> [--order file] [--name <text>] [--parent <id>]
getplanq task get <file> <task-id>
addplanq task add <file> --id <id> --name <name> [task fields] [placement]
updateplanq task update <file> <task-id> [task fields] [placement]
deleteplanq task delete <file> <task-id>

Exit codes ​

CodeMeaning
0Success
1Invalid plan, operation, or source baseline
2Argument 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.
  • --effort <N>pd sets positive person-day effort with at most four decimal places; task update --clear effort removes it.
  • Effort is mutually exclusive with explicit start/end. Switch modes atomically by setting one and clearing the other in the same update.

Examples ​

bash
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 --first

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

PlanQ documentation