CLI Reference

CLI reference

Generated from planx 0.14.0.

Global flags

Flag	Meaning
--dir <PATH>	Use a different store instead of ~/.planx.
--json	Machine-readable output. Available on every read command.
--no-color	Disable ANSI colour. NO_COLOR is honoured too.
--help	Show usage for this command.

NO_COLOR is honoured, and PLANX_DIR sets the store the same way --dir does.

Run by you

The normal interactive commands: review plans and configure hand-offs.

planx diff

Review a plan, or print a diff between two versions.

planx [diff] [id] [vA] [vB] [--print] [--plain|--rich] [--stat]

In a terminal this opens the review TUI on the diff against the previous version — you opened v4 because v4 is new, and what is new about it is the diff. Press d to see the plan on its own instead. Select lines, comment on them or rewrite them, then submit — an empty submit is how you say the plan is fine. The command name is optional in front of a plan — planx <id> is the same thing. Piped or with --print it writes the diff to stdout and exits. With no arguments it opens a picker.

Flag	Meaning
--print	Non-interactive: write the diff to stdout and exit.
--plain	Raw unified diff, no rich rendering.
--rich	Rich rendering (the default).
--stat	Just the summary line.

planx diff guard-clock-a3f9
planx diff guard-clock-a3f9 v1 v3 --print --plain

planx defaults

Your own commands for the review hand-off.

planx defaults [--revise CMD] [--execute CMD] [--json]

Set once, globally, and the review offers them as two more rows on the list s opens — above the ones planx builds itself, so a command you wrote is what 1 picks. planx takes the command you stored and puts the skill invocation on the end of it as one quoted argument, spelt $planx … for a command that runs Codex and /planx … for everything else, because that is how each agent invokes a skill. So the command has to be written to take a trailing prompt, and the agent it names needs the planx skill installed for that prompt to mean anything there. With a flag it sets and prints; an empty value clears. With neither, in a terminal, it opens a screen. Rewriting one of these rows in the review before running it stores what you typed, minus the appended prompt, as the new default.

Flag	Meaning
--revise <CMD>	Your own command for the revise hand-off. Empty clears it.
--execute <CMD>	Your own command for the execute hand-off. Empty clears it.

planx defaults
planx defaults --revise "codex exec --full-auto"
planx defaults --execute ""

Housekeeping you run

Install, remove, update and repair PlanX.

planx add-skills

Add the planx skills to Claude Code or Codex, and seed the store.

planx add-skills [--no-store] [--local]

Detects Claude Code and Codex installations on this machine, writes a skill into each, and seeds ~/.planx, showing each step as it happens. Touches no agent settings files. Idempotent, and it marks what it wrote so remove-skills removes only that. npm runs this after every install, so an upgrade refreshes your skills without being asked twice; run it by hand to pick up an agent you installed since. For another agent, use its skill installer and configure its hand-off with planx defaults.

Flag	Meaning
--no-store	Write skills only; leave ~/.planx alone.
--local	Write into ./.claude/skills for a repo-local install.
--agent <NAME>	Only this agent. Repeatable.

planx remove-skills

Remove what add-skills wrote, and offer to delete the store.

planx remove-skills [--local]

Removes only the skill directories planx wrote — one you edited by hand is left alone and reported. Then it asks whether to delete ~/.planx, naming the path and how many plans are in it. A non-interactive run never deletes and never asks.

Flag	Meaning
--local	Remove from ./.claude/skills instead of $HOME.

planx update

Install the latest planx from npm.

planx update

Runs npm install -g @thisisnsh/planx@latest --foreground-scripts and hands the terminal to npm, so its output scrolls and the add-skills its postinstall runs is drawn live at the end of it. Checks the registry first and does nothing when you are already on the latest. npm’s exit code is this command’s exit code.

planx doctor

Check the store for problems and rebuild the index.

planx doctor

Run by your agent

The PlanX skill normally runs these protocol commands. They remain available for manual and scripted workflows.

planx capture

Store a version of a plan.

planx capture [--plan-id ID] [--title T] [--stdin|--file F] [--parent VER]

Reads the plan from stdin or a file and appends it as a new version. Capturing content identical to the current latest is a no-op, so skills can call it defensively.

Flag	Meaning
--plan-id <ID>	Append to this plan. Omit to create a new one.
--title <T>	Plan title. Defaults to the H1 of the plan text.
--name <N>	Pin the plan id instead of deriving it from the title.
--stdin	Read the plan from stdin. Implied when stdin is a pipe.
--file <F>	Read the plan from a file.
--parent <VER>	Version this revises. Defaults to the latest.
--source <NAME>	Which agent produced this (claude, codex, …).
--note <N>	One line about what changed in this version.
--agent <NAME>	Agent identifier recorded on the version.
--session-id <ID>	The agent session that wrote this, so planx can resume it.

planx capture --stdin --title "Guard the clock regression" < plan.md
planx capture --plan-id guard-clock-a3f9 --parent v2 --stdin

planx revise

Pick a plan back up: the feedback left on it.

planx revise <id> <version> [--json]

One read with everything asked of the plan: the stored version verbatim, each comment against the lines it quotes, and every line the reviewer rewrote by hand. The plan comes back so the next one is edited from the stored bytes rather than retyped from memory, which re-wraps untouched paragraphs into the diff. Comments left on an earlier version whose quoted text is still present word for word are reported as probably never addressed. A version nobody has reviewed comes back all the same, saying so — what the revision is towards there is what the user asked for in the chat. Safe to run twice; it waits for nothing. The version is required, not defaulted: this command arrives as a line copied out of a review of one particular version, and by the time it runs the plan may have a newer one. Say latest when latest is what you mean.

planx revise guard-clock-a3f9 v3
planx revise guard-clock-a3f9 latest

planx execute

Hand the plan over to be built, and mark the version being built.

planx execute <id> <version> [--session-id ID] [--agent NAME] [--no-mark]

Everything revise returns — the stored version verbatim, the comments, the lines the reviewer rewrote, anything still unaddressed from earlier — closing on the instruction to build it rather than to revise and capture. It also marks the version as the one that was executed, which is what turns its row green in the picker. The execute skill runs it before its first edit, so the mark is true whichever route reached the build — the agent planx launched, a command you pasted yourself, or /planx execute typed from scratch. planx does not mark on launch, because a launch you immediately ctrl+c out of built nothing. Running it twice restamps the time rather than failing, and a second run that names no session keeps the one already stored.

Flag	Meaning
--session-id <ID>	The agent session doing the building, so ctrl+r can resume it.
--agent <NAME>	Which agent that is, when the process walk cannot say.
--no-mark	Print the hand-off without recording a build.

planx execute guard-clock-a3f9 v3 --session-id 0f2c…
planx execute guard-clock-a3f9 v3 --no-mark

planx show

Print a stored version of a plan.

planx show <id> <version> [--plain|--rich]

The version is required, as it is on revise and execute — a plan reference with no version means whatever was captured most recently, which is not what a command written against a reviewed version meant. latest says it explicitly.

Flag	Meaning
--plain	Raw markdown source.
--rich	Syntax-highlighted.

planx show guard-clock-a3f9 v3 --plain
planx show guard-clock-a3f9 latest

planx list

List stored plans, newest first.

planx list [--here] [--json]

Flag	Meaning
--here	Only plans captured in the current directory.