Skip to main content

pt CLI reference

Every subcommand the pt CLI supports. Each section has a stable slug-anchor (e.g. #list-tasks, #create-issue) so an agent or PR review can cite a specific subcommand by URL.

Every subcommand supports the global flags:

  • --json — emit structured JSON instead of Markdown. Use this in agent loops.
  • --help / -h — per-subcommand usage.

The CLI is implemented in tools/mcp-server/src/cli-commands.ts — that file is the source of truth for argument shapes. The MCP server (tools/mcp-server/src/server.ts) exposes the same operations as MCP tools — see MCP server setup.

Orientation​

workspace​

Returns the current user, the dogfood programme (Constellation Platform Development), and the top 3 IN_PROGRESS tasks per project. Run this once at the start of every agent session instead of reading docs/constellation/DEVELOPMENT_PLAN.md for current status.

pt workspace
pt workspace --json

No arguments. Output is a Markdown block that pastes cleanly into agent context.

find-project​

Resolve a free-form hint to a Project Tracker project. Hints can be a UUID, project name, task-key prefix (PLT, CAT, etc.), or a repo path that maps to a project per memory/pt-projects.md. Use this before any task-creation flow — never hardcode project UUIDs.

pt find-project apps/catalog/src/page.tsx
pt find-project PLT
pt find-project "Stella Catalog"

Argument: <hint> (positional, required).

Projects & programmes​

list-projects​

List projects in the current org. Use the dedicated programme subcommand if you only want the dogfood programme.

pt list-projects
pt list-projects --search Catalog
pt list-projects --status ACTIVE

Flags: --search <text>, --status <status>, --json.

get-project-overview​

Project details: stages, custom statuses, summary stats.

pt get-project-overview INF
pt get-project-overview <project-uuid>

Argument: <project> (UUID or prefix, required).

initiative​

Get an initiative with all its projects. The Constellation dogfood initiative ID is in memory/pt-projects.md; usually you want pt workspace instead.

pt initiative <initiative-id-or-name>

Argument: <initiative-id-or-name> (UUID or name substring, required).

list-initiatives​

List initiatives in the active organisation, with status / search filters.

pt list-initiatives
pt list-initiatives --status ACTIVE
pt list-initiatives --search platform

create-initiative​

Create a new initiative. New initiatives are always created ACTIVE with no project links; use update-initiative to change status and create-project / update-project to link projects.

pt create-initiative --name "Q3 platform hardening" --start 2026-07-01
pt create-initiative --name "Migration" --start 2026-07-01 --end 2026-12-31 --description "..."

update-initiative​

Update an initiative's name, description, status, or dates.

pt update-initiative <id-or-name> --name "Renamed" --status ON_HOLD

delete-initiative​

Delete an initiative. Cascades to delegate links; the linked projects themselves are not deleted but lose their initiative reference.

pt delete-initiative <id-or-name>

create-project​

Create a new project. Accepts an optional --prefix (returns 409 Conflict if taken in the tenant) and an optional --initiative link (UUID or name).

pt create-project --name "Catalog" --start 2026-07-01 --prefix CAT
pt create-project --name "Q3 work" --start 2026-07-01 --initiative "Constellation Platform Development"

update-project​

Update a project's name, description, status, dates, prefix, issue prefix, or initiative link. Pass --initiative "" to clear the initiative link.

pt update-project CAT --status COMPLETED
pt update-project CAT --initiative ""

delete-project​

Permanently delete a project and all its tasks, issues, stages, comments, and time entries. Irreversible.

pt delete-project CAT

Tasks​

list-tasks​

List tasks in a project, with optional status / search / assignee filters.

pt list-tasks INF --status IN_PROGRESS
pt list-tasks PT --search "promote issue" --limit 20
pt list-tasks <project-uuid> --assignee <user-uuid> --json

Argument: <project> (UUID, name, prefix, or repo path — required). Flags: --status, --search, --assignee <uuid>, --limit <n> (defaults to 50), --json.

get-task​

Full details of one task. Both arguments are required.

pt get-task INF INF-31
pt get-task INF INF-31 --json

Arguments: <project> (UUID, name, prefix, or repo path — required), <taskKey-or-uuid> (required).

create-task​

Create a planned-work task. Use create-issue for bugs / incidents / support tickets. The project goes through --project, not as a positional argument.

pt create-task --project INF --title "Wire OpenAPI for Catalog" \
  --description "Mirror PT's openapi.ts pattern."

Flags: --project <hint> (required — UUID, name, prefix, or repo path), --title (required), --description, --assignee <uuid>, --due <ISO>, --json.

update-task​

Update a task. For issues use update-issue / transition-issue / resolve-issue for those fields specifically. Both positional arguments are required — task keys are scoped per project, so the project hint must be supplied.

pt update-task INF INF-31 --status IN_PROGRESS
pt update-task INF INF-31 --progress 90
pt update-task INF INF-31 --assignee <user-uuid>

Arguments: <project> (UUID, name, prefix, or repo path), <taskKey-or-uuid>. Flags: --title, --status, --progress (0–100), --assignee <uuid>, --due <ISO>, --json.

Issues​

list-issues​

List issues (bugs / incidents / support tickets) with optional filters.

pt list-issues
pt list-issues --project INF --severity HIGH --status OPEN
pt list-issues --search "RLS" --json

Flags: --project <hint>, --severity (CRITICAL / HIGH / MEDIUM / LOW), --status (OPEN / IN_PROGRESS / CLOSED / RESOLVED / REOPENED), --search, --json.

get-issue​

Full details of one issue.

pt get-issue ISS-12

Argument: <issue> (key or UUID, required).

create-issue​

Create a bug / defect / incident / support ticket. Use create-task for planned work. Heuristic: if the user says "let's plan to do X" → task; if they say "X is broken, track it" → issue. The project goes through --project, not as a positional argument. Assignment is a separate operation — use assign-issue after creation; the create endpoint does not accept an assignee.

pt create-issue --project INF --title "RLS misconfigured on identity.users" \
  --severity HIGH \
  --description "withTenantContext was missing from the new endpoint."

Flags: --project <hint> (required), --title (required), --description, --severity (CRITICAL / HIGH / MEDIUM / LOW), --json.

update-issue​

Update issue title / description / due-date. Use escalate-issue for severity, assign-issue for assignee, transition-issue for status, resolve-issue for the resolved-with-reason form.

pt update-issue ISS-12 --title "RLS misconfigured (corrected scope)"

Argument: <issue> (key or UUID, required). Flags: --title, --description, --due <ISO>, --json.

assign-issue​

Assign an issue to a user (POST /api/issues/:id/assign). The assignee goes through --assignee, not as a positional argument. Pass --assignee "" (empty string) to unassign.

pt assign-issue ISS-12 --assignee <user-uuid>
pt assign-issue ISS-12 --assignee ""        # unassign

Argument: <issue> (key or UUID). Flags: --assignee <uuid> (required, empty string to unassign), --json.

escalate-issue​

Change severity (POST /api/issues/:id/escalate). The severity goes through --severity, not as a positional argument.

pt escalate-issue ISS-12 --severity CRITICAL

Argument: <issue> (key or UUID). Flags: --severity (required — CRITICAL / HIGH / MEDIUM / LOW), --json.

transition-issue​

Move an issue between OPEN / IN_PROGRESS / CLOSED / REOPENED. For the RESOLVED-with-reason path use resolve-issue. The target status goes through --to, not as a positional argument.

pt transition-issue ISS-12 --to IN_PROGRESS

Argument: <issue> (key or UUID). Flags: --to (required — OPEN / IN_PROGRESS / CLOSED / REOPENED), --json.

resolve-issue​

Resolve an issue with a resolution code (sets status to RESOLVED). The resolution goes through --resolution, not as a positional argument.

pt resolve-issue ISS-12 --resolution FIXED
pt resolve-issue ISS-12 --resolution WONT_FIX

Argument: <issue> (key or UUID). Flags: --resolution (required — FIXED / WONT_FIX / DUPLICATE / DEFERRED), --json.

Stages​

list-stages​

List the stages in a project's stage-gate pipeline.

pt list-stages PT

Argument: <project> (prefix or UUID, required).

See also​