Skip to Content
ReferenceCLI commands

CLI commands

The command is pcs. Run pcs <command> --help for the options of any command, and pcs --version for the installed version. Several commands accept --json for scripts.

Setup

CommandWhat it does
pcs initCreates .pcs/ in the current project (git-excluded, owner-only)
pcs doctor [--fix] [--json]Checks the installation and repairs what it safely can. See Maintenance
pcs deinit [--yes]Removes everything PCS added to a project. A dry run unless --yes is given
pcs config show, pcs config initShows or scaffolds the global and project policy files
pcs connect <client>Writes the MCP entry for claude-desktop, cursor or claude-code. Options: --global (Cursor), --read-only, --allow-test, --portable, --remove
pcs agents install, pcs agents uninstallAdds or removes the marked instruction block in CLAUDE.md, AGENTS.md and Cursor rules
pcs hooks install, pcs hooks uninstall, pcs hooks statusManages Claude Code hooks
pcs autostart install, pcs autostart uninstall, pcs autostart statusStarts the watcher at login

Work

CommandWhat it does
pcs session start --agent <name>Starts a session for an agent
pcs session end --reason <reason>Ends the active session. limit is one example reason
pcs session current, pcs session listShows the active session, or lists sessions
pcs task add, pcs task list, pcs task updateManages tasks. A task’s status is never rewritten by evidence
pcs note add <kind> "<text>", pcs note list, pcs note resolveRecords notes such as task and next. Every note is reported
pcs snapshot [take], pcs snapshot list, pcs snapshot diffRecords the repository state (immutable)
pcs test [--task <id>] -- <command>Runs a command itself and records exit code, duration and output as verified evidence
pcs evidence list, pcs evidence show, pcs evidence linkBrowses test runs and links them to tasks

Handoff

CommandWhat it does
pcs handoff [--out <file>] [--stdout]Writes .pcs/HANDOFF.md, or elsewhere, or prints it
pcs resume --agent <name> [--prompt]Checks the handoff, snapshots the repo and prints the brief. --prompt wraps it as a paste-ready prompt
pcs statusShows the current state of the project
pcs watchObserves the project in the background. See Watcher

Trust

CommandWhat it does
pcs verify [--anchor <file>]Checks the hash chain, and optionally a signed anchor
pcs anchorWrites a signed anchor of the current log head
pcs log [--type <pattern>] [--provenance <level>] [--after <value>] [-n <count>]Shows recent events, oldest first
pcs export [--format json or md] [-o <file>] [--from <id>] [--to <id>] [--check <file>]Writes, or checks, an audit export

Many projects

CommandWhat it does
pcs workspace add, pcs workspace remove, pcs workspace listManages the registry of projects
pcs dashboard [--workspace]Starts the read-only dashboard on 127.0.0.1
pcs mcp [--workspace] [--project <path>] [--agent <name>] [--read-only] [--allow-test]Starts the MCP server. See MCP tools

Exit codes

CodeMeaning
0OK
1Error. For pcs test: the command did not pass. For pcs doctor: a check failed
2Integrity failure. Handoff, resume and export still produce their output, flagged

The reference above lists the options documented in the project’s README and decision records. Run pcs <command> --help for the authoritative list for your installed version.

Last updated on