CLI reference

Generated from planx 0.4.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.

planx capture

Store a version of a plan.

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

Reads the plan from stdin or a file and appends it as a new version. Refuses to write a version that modifies a locked block, printing the offending diff and the command to ask for an unlock. 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.
--splice	Expand [[planx:keep …]] markers before writing.
--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.

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

planx revise

Pick a plan back up: the feedback on it, and its locks.

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

One read with everything asked of the plan: each comment against the lines it quotes, and the locked blocks. It does not return the plan itself — the agent that wrote it already has it, and planx show <id> --plain is there for a session that does not. Comments left on an earlier version whose quoted text is still present word for word are reported as probably never addressed. Safe to run twice; it waits for nothing.

planx revise guard-clock-a3f9

planx unlock

Open one locked block for a single capture.

planx unlock <id> <lock-id> --reason "..."

Run by the agent after it has explained the change and the user has agreed. The grant authorises exactly one capture that may modify the block, then burns, and the lock re-arms on whatever was written. The reason is recorded on the grant, which is what makes a self-issued unlock reviewable afterwards — see planx locks.

Flag	Meaning
--reason <R>	Why the block has to change. Required.

planx unlock guard-clock-a3f9 L2 --reason "the R2 path replaced this entirely"

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 and comment, lock or unlock them, then submit or approve. 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 show

Print a stored version of a plan.

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

Flag	Meaning
--plain	Raw markdown source.
--rich	Syntax-highlighted with a lock gutter.
--skeleton	Collapse locked blocks to [[planx:keep …]] markers.

planx list

List stored plans, newest first.

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

Flag	Meaning
--here	Only plans captured in the current directory.
--approved	Only approved plans.
--unapproved	Only plans that never reached approve.

planx locks

Show a plan’s locks and any outstanding unlock grants.

planx locks <id> [--json]

The one command besides the review a person runs by hand. It is the only way to see that an agent issued itself an unlock and what reason it recorded, and the unlock handshake is worth nothing if that record cannot be read.

planx add-skills

Add the planx skills to your agents, and seed the store.

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

Detects which agents are 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.

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