pm-cli (pm)

pm is a git-native project management CLI for humans and coding agents. It stores work items in reviewable repository files, records every mutation in append-only history, and defaults to sparse TOON output so agents can spend fewer tokens while still getting deterministic data.

Start Here

Need	Read
Install and create the first item	Quickstart
New maintainer onboarding	Onboarding
Agent workflow and token-minimal loops	Agent Guide
Command families and examples	Command Reference
Shell, CI, and machine-client composition	CLI Scripting Contract
Settings, storage, search, and output	Configuration
Safe test execution and linked tests	Testing
Security reporting and resilience controls	Security Policy, Security Governance
Package and extension authoring	Packages and Extensions, SDK, Context Integrity, Customization Primitives, Evidence Traceability, and Agent Runtime Primitives
Maintainer release process (daily auto-release + local parity)	Releasing
Contributor internals	Architecture

Full documentation starts at docs/README.md.

For optional in-terminal docs routing, use the canonical guide topic map.

Install

pm-cli requires Node.js 22.18 or newer (extensions and packages are authored and loaded as TypeScript via Node's native type stripping, so no compiled .js is shipped or committed).

npm install -g @unbrained/pm-cli
pm --version
pm --help

Use the npm registry package for global installs and updates. Avoid npm install -g from the GitHub git URL for routine updates; npm can leave a stale global shim when replacing git-sourced installs. If that happens, run bash scripts/install.sh --repair from a checkout or npm uninstall -g @unbrained/pm-cli && npm install -g @unbrained/pm-cli.

Project-local invocation also works:

npx --yes @unbrained/pm-cli@latest --help

pm packages use the same package-first vocabulary:

pm package install '*'
pm package install ./my-package
pm package manage --project
pm package doctor --detail summary
pm package upgrade --dry-run

The hidden legacy pm extension ..., pm install ..., and pm upgrade ... aliases remain available for existing automation. They preserve canonical output and emit one migration hint on stderr unless ux.deprecation_hints is disabled; for example, pm install guide-shell --project maps to the canonical command.

60 Second Example

pm init

pm create \
  --title "Fix stale lock restore failure" \
  --description "Restore should retry cleanly after stale lock cleanup." \
  --type Issue \
  --status open \
  --priority 1 \
  --tags "restore,locks" \
  --ac "Restore succeeds after stale lock cleanup and has regression coverage." \
  --create-mode progressive

pm list --status open --limit 10
pm claim <item-id>
pm update <item-id> --status in_progress --message "Start implementation"
pm files <item-id> --add path=src/core/lock/lock.ts
pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",timeout_seconds=240
pm test <item-id> --run --progress
pm close <item-id> "Fixed stale lock retry path; linked test passed."
pm release <item-id>

Agent Loop

Use pm next to get the single highest-priority ready item (and why), or pm context for the full snapshot, then search before creating anything:

pm next                                          # the next actionable item + rationale, ready/blocked queues
pm context --limit 10
pm search "keywords for the requested work" --limit 10
pm list --status open --limit 20
pm list --status in_progress --limit 20

If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the Agent Guide.

For token-aware local routing, install guide-shell with pm package install guide-shell --project, then use pm guide workflows and drill into related topics (commands, skills, release) only when needed.

Core Model

• Items live under .agents/pm/ as TOON by default, with JSON-front-matter markdown also supported.
• History lives in .agents/pm/history/<id>.jsonl and is append-only.
• Statuses are draft, open, in_progress, blocked, closed, and canceled.
• Built-in types include Epic, Feature, Task, Chore, Issue, Decision, Event, Reminder, Milestone, Meeting, and Plan.
• Output defaults to sparse TOON. Use --json for strict parsing.
• pm contracts is the machine-readable command and schema contract surface for agents.
• pm guide is the optional local progressive-disclosure docs and skills index for agents after installing guide-shell.

Search behavior (lexical search.tuning weights, hybrid --semantic-weight, query expansion, reranking, and vector-store options) is fully configurable — see Search Configuration.

License

MIT