CLI Reference

Install the CLI globally from npm (Node ≥ 20):

npm i -g @plandesk/cli

This provides the plandesk binary and bundles the web UI. All commands below assume a global install. Contributors running from a cloned repo can use packages/plandesk-cli/bin/plandesk instead.

plandesk help [--commands]
plandesk init [--data-dir <dir>]
plandesk serve [--port 3847] [--strict-port] [--host <addr>] [--data-dir <dir>]
plandesk token create --name <name> [--data-dir <dir>]
plandesk export --project <id> --out <file.json> [--data-dir <dir>]
plandesk import --in <file.json> [--data-dir <dir>]
plandesk connect [--repo <dir>] [--project <id|name>] [--url <url>] [--token <token>] [--agent claude|codex|both] [--print]
plandesk disconnect [--repo <dir>]
plandesk doctor [--data-dir <dir>] [--repo <dir>]

# Collaboration (share a project with a client or team)
plandesk publish --remote <url> [--project <id>] [--sync-token <t>] [--repo <dir>]
plandesk push [--project <id>] [--repo <dir>]
plandesk pull [--project <id>] [--repo <dir>]
plandesk sync --watch [--project <id>] [--repo <dir>]
plandesk share create --audience <name> [--public] [--invite <email[,email]>] [--allow-submit] [--expires <30d>] [--project <id>]
plandesk deploy [target]

Commands

Command	Purpose
help	A crash course (orientation + key commands + doc links) for humans and agents; help --commands prints the full grammar
init	Create workspace DB and run migrations
serve	Start REST + SSE + MCP + web UI (default 0.0.0.0:3847, all interfaces)
token create	Create MCP bearer token (shown once)
export / import	Lossless plandesk-export-v1 JSON round-trip
connect / disconnect	Bind / unbind a repo to a project + agent configs; re-run connect after upgrading to regenerate artifacts
doctor	Check DB health; with --repo, validate binding + MCP reachability
version	Print the installed CLI version (also --version); see Upgrading

Collaboration

Share a planned project with a client or another team over a read-only live portal, and take their issues back into your plan. Full walkthrough: Plan → share → build with your team; architecture: Collaboration & sync.

Command	Purpose
deploy	List deploy guides; deploy <target> prints one for a coding agent to run
publish	Register a project with a sync server + first push (writes git-ignored token)
push	Push the allow-list projection for each active share
pull	Fetch participant submissions into the local triage inbox
sync --watch	Stream local changes to the portal (~2s) so participants see status live
share create	Mint a participant share (token shown once); prints the <portal>/p/<token> link

share create flags: --public (open named-join) or --invite a@b,c@d (invite-only); --allow-submit (let the audience file issues); --expires 30d (h/d/w). The sync token lives only in git-ignored .plandesk/sync-token (or PLANDESK_SYNC_TOKEN); participant tokens are stored hashed.

Options

Flag	Default	Purpose
--data-dir	nearest .plandesk/ walking up from cwd, then PLANDESK_DATA_DIR, then ~/.plandesk	Workspace directory
--repo	cwd	Target repository directory
--port	3847	Preferred HTTP port for serve (auto-rotates to the next free port if busy)
--strict-port	—	Fail instead of rotating when the port is in use
--host	0.0.0.0	Bind address (PLANDESK_HOST)
--project	—	Project id or name for connect/export
--url	http://127.0.0.1:3847	Plan Desk server URL for connect
--token	—	MCP token for connect
--agent	detect	Agent config target for connect
--print	—	Dry-run connect without writing files
--out	—	Output file for export
--in	—	Input file for import

Environment variables

Variable	Default	Purpose
PLANDESK_DATA_DIR	(see --data-dir)	Workspace directory override
PLANDESK_HOST	0.0.0.0	Bind address
PLANDESK_AUTH_PASSWORD	(unset)	When set, enables HTTP basic auth on the UI and REST API
PLANDESK_MCP_TOKEN	(unset)	Overrides the token read from .plandesk/token

Validation and metrics

pnpm validate   # live health, serve, MCP list-tools smoke
pnpm metrics    # v1 performance targets (see Validation & Metrics)