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 | | Settings, storage, search, and output | Configuration | | Safe test execution and linked tests | Testing | | Package and extension authoring | Packages and Extensions, SDK, and Customization 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 install '*'
pm install ./my-package
pm package manage --project
pm package doctor --detail summary
pm upgrade --dry-run

The legacy pm extension ... command remains available for existing automation.

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-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-open --limit 20
pm list-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 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