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
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
Extension authoring	Extensions and SDK
Maintainer release process (daily auto-release + local parity)	Releasing
Contributor internals	Architecture

Full documentation starts at docs/README.md.

Install

pm-cli requires Node.js 20 or newer.

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 @unbrained/pm-cli --help

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,scope=project
pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",scope=project,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 context first, then search before creating anything:

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.

Release Automation

• Daily release preparation runs in .github/workflows/auto-release.yml.
• Tag-driven publishing remains in .github/workflows/release.yml.
• Local parity commands:
  • pnpm release:pipeline:dry-run
  • pnpm release:pipeline -- --telemetry-mode required

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, and Meeting.
• Output defaults to sparse TOON. Use --json for strict parsing.
• pm contracts is the machine-readable command and schema contract surface for agents.

Tracker References

This documentation refresh is tracked through pm:

• pm-3042 - documentation overhaul epic
• pm-r9gu - documentation structure feature
• pm-1sb2 - README and public docs rewrite task

Docs should link to relevant pm items, and pm items should link back to changed docs through pm docs.

Privacy Boundary

Private production operations material is local-only, gitignored, and intentionally not linked from public documentation or packaged release files. Keep public docs focused on user-facing CLI behavior and safe contribution workflows.

License

MIT