CLI

Planner adds the pst tickets, pst statuses, and pst tags commands, plus workflow commands under pst pstdio-planner. People and agents use the same commands.

Run pst <command> --help to see the options in your installed version.

Before you start

Run the commands inside a project folder that is linked to Prompt Studio, or pass --project-id <id>. Add --json to get the full result as JSON.

Values that name a ticket, status, tag, or tag option accept an ID or a name. Names are not case-sensitive. A ticket can be named by its ID, such as PS-12.

Tickets

pst tickets list [--status <status>] [--tags <tag>...] [--parent <ticket>] [--archived] [--draft]
pst tickets create [--title <title>] [--content <markdown>] [--status <status>] [--tags <tag>...] [--parent <ticket>] [--depends-on <ticket>...]
pst tickets add [same options as create]
pst tickets panel --id <ticket>
pst tickets update --id <ticket> [options]
pst tickets archive --id <ticket>
pst tickets unarchive --id <ticket>
pst tickets delete --id <ticket>
pst tickets link-review --id <ticket> --url <url> [--title <title>]
pst tickets proposal-refined --id <ticket>
pst tickets implement --id <ticket> [--agent '{"harnessId":"<agent-id>"}']

list hides drafts and archived tickets. Use --draft or --archived to list only those.

--tags takes tag option names, such as High or Bug, and can be repeated.

create and add do the same thing. When you pass --content, Planner takes the title from its first line and ignores --title.

panel returns the complete stored ticket.

update can change --content, --status, --tags, --parent, --depends-on, and --blocked-reason. Use --unlink-parent to remove the parent.

unarchive makes an archived ticket active again. Its status, tags, order, and content stay the same.

link-review attaches a review URL, such as a pull request, to the ticket. Running it again with the same URL keeps the existing link.

proposal-refined tells people that a proposal ticket is ready for review. Prompt Studio shows a Review proposal notification.

implement moves the ticket to In Progress and starts one agent session with the implement-ticket prompt. It does not create a worktree or a managed attempt. Use run-attempt for that. --agent takes an agent ID from pst agents list.

Dependencies

--depends-on takes ticket IDs and can be repeated. Both create and update accept it:

pst tickets create --title "Ship the flag" --depends-on PS-12 --depends-on PS-13
pst tickets update --id PS-14 --depends-on PS-12

On update, the flag replaces all dependencies. If you leave it out, the dependencies stay as they are, so a status change never drops them. Use --clear-depends-on to remove every dependency.

An unknown ticket ID fails the command, names the ID, and changes nothing. A dependency that leads back to the ticket itself, directly or through other tickets, is rejected and the ticket stays unchanged.

Edit a ticket as a local file

pst tickets write --title <title> [--status <status>] [--tags <tag>...] [--user-prompt <text>] [--parent <ticket>]
pst tickets save --id <ticket> [--status <status>]
pst tickets pull [--id <ticket>] [--force]
pst tickets files --id <ticket>
pst tickets templates
pst tickets apply-template --id <ticket> --template <template> [--var <key=value>...]

write creates a draft ticket and writes it to .pstdio/tickets/<ticket>/ticket.md in the project folder. Edit that file and any files in its files/ folder, then run save to store your changes:

pst tickets write --title "Fix login" --status Todo --tags High
pst tickets save --id PS-12

save reads the description, tags, parent, dependencies, and files from the local ticket. Its only other option is --status. In the file’s front matter (the block at the top of the file), depends_on takes the same ticket IDs as --depends-on. depends_on: [] removes every dependency.

pull without --id pulls all active tickets. It keeps existing local files unless you pass --force.

apply-template replaces the content of the local file with a ticket template. It fills in TICKET_ID, TICKET_TITLE, and CREATED_AT. Pass other values with --var key=value. Run save afterwards to store the result. templates lists the template names, and files lists the ticket’s files.

Link workspaces and sessions

pst tickets link --id <ticket> (--workspace <workspace> | --session <session-id>)
pst tickets unlink --id <ticket> (--workspace <workspace> | --session <session-id>)
pst tickets workspaces --id <ticket>
pst tickets worktrees list --id <ticket>
pst tickets worktrees remove-all --id <ticket>

For example, create one Git worktree and link two tickets to it:

pst workspaces create --provider pstdio.worktree
pst tickets link --id PS-1 --workspace WS-19
pst tickets link --id PS-2 --workspace WS-19
pst tickets workspaces --id PS-2

For separate workspaces, create one for each ticket. Other workspace types use their own provider ID and options. You can also link the project folder or a remote workspace by its ID.

link and unlink need exactly one target. A workspace can be named by its ID, such as WS-19. A session needs its full ID. Linking the same target again does not add a duplicate. Linking does not copy ticket drafts.

unlink removes one link and keeps the others. You cannot unlink a ticket from the workspace or the sessions of its own managed attempt.

worktrees remove-all removes every worktree linked to the ticket. It refuses to remove anything if one of them is shared with another ticket. Unlink the shared worktree from this ticket first, then run the cleanup again.

When you archive a ticket, Planner archives a linked workspace only after every ticket linked to it is archived. The project folder, and workspace types that cannot be archived, stay available. Unarchiving a ticket does not bring its archived workspaces back. Create a new workspace to continue the work.

Statuses

pst statuses list
pst statuses create --label <label> [--color <color>] [--icon <icon>] [options]
pst statuses update --status-id <status> [options]
pst statuses reorder --status-ids <json>
pst statuses set-default --status <status>
pst statuses delete --status <status>

create and update accept --can-create, --can-drag-in, --can-drag-out, and --column-actions <json>. Use --no-can-create, --no-can-drag-in, or --no-can-drag-out to turn a behavior off. --column-actions takes a JSON list, such as '["archive_all"]' for the Archive all action. update also accepts --label, --color, --icon, and --sort-order.

pst statuses create --label "Triaging" --color amber
pst statuses update --status-id backlog --label Backlog --color gray --icon status-backlog
pst statuses reorder --status-ids '["backlog","ready","in-progress","blocked","in-review","done"]'
pst statuses set-default --status Todo
pst statuses delete --status "Triaging"

--status-id and --status-ids take status IDs, not names. The default statuses have the IDs backlog, ready (Todo), in-progress, blocked, in-review, and done. See Tags and statuses for the default set and the colors.

Tags

pst tags list
pst tags create --name <name> [--type <single_select|multi_select>]
pst tags update --tag-id <tag> [--name <name>] [--type <type>] [--sort-order <number>]
pst tags delete --tag <tag>
pst tags options create --tag-id <tag> --name <name> [options]
pst tags options update --tag-id <tag> --option-id <option> [options]
pst tags options delete --tag-id <tag> --option-id <option>
pst tags apply-draft --tag-id <tag> [options]

The default type is single_select. The option commands accept --color, --icon, and --description. options update also accepts --name and --sort-order.

pst tags create --name Priority --type single_select
pst tags update --tag-id default-priority --sort-order 0
pst tags options update \
  --tag-id default-priority \
  --option-id default-priority-urgent \
  --color red \
  --icon flame
pst tags delete --tag Priority

apply-draft changes a tag and its options in one write. Pass JSON lists with --options-to-create, --options-to-update, and --option-ids-to-delete. Use the single option commands to change option order.

Planner commands

Every Planner command that the CLI can run is also available under pst pstdio-planner. The commands above are shorter names for these:

Planner command	Short name
pst pstdio-planner list-tickets	pst tickets list
pst pstdio-planner create-ticket	pst tickets create, add
pst pstdio-planner get-ticket	pst tickets panel
pst pstdio-planner update-ticket	pst tickets update
pst pstdio-planner archive-ticket	pst tickets archive
pst pstdio-planner unarchive-ticket	pst tickets unarchive
pst pstdio-planner delete-ticket	pst tickets delete
pst pstdio-planner link-review	pst tickets link-review
pst pstdio-planner proposal-refined	pst tickets proposal-refined
pst pstdio-planner implement-ticket	pst tickets implement
pst pstdio-planner write-ticket	pst tickets write
pst pstdio-planner save-ticket	pst tickets save
pst pstdio-planner pull-ticket	pst tickets pull
pst pstdio-planner list-ticket-files	pst tickets files
pst pstdio-planner list-ticket-templates	pst tickets templates
pst pstdio-planner apply-ticket-template	pst tickets apply-template
pst pstdio-planner link	pst tickets link
pst pstdio-planner unlink	pst tickets unlink
pst pstdio-planner ticket-workspaces	pst tickets workspaces
pst pstdio-planner ticket-worktrees-list	pst tickets worktrees list
pst pstdio-planner ticket-worktrees-remove-all	pst tickets worktrees remove-all
pst pstdio-planner ticket-status read	pst statuses list
pst pstdio-planner ticket-status create	pst statuses create
pst pstdio-planner ticket-status update	pst statuses update
pst pstdio-planner ticket-status reorder	pst statuses reorder
pst pstdio-planner ticket-status set-default	pst statuses set-default
pst pstdio-planner ticket-status delete	pst statuses delete
pst pstdio-planner ticket-tag read	pst tags list
pst pstdio-planner ticket-tag create	pst tags create
pst pstdio-planner ticket-tag update	pst tags update
pst pstdio-planner ticket-tag delete	pst tags delete
pst pstdio-planner ticket-tag create-option	pst tags options create
pst pstdio-planner ticket-tag update-option	pst tags options update
pst pstdio-planner ticket-tag delete-option	pst tags options delete
pst pstdio-planner ticket-tag apply-draft	pst tags apply-draft

Workflow commands

These commands have no short name. Most of them are meant for agents and automations, and their options can include revision IDs, report IDs, and expected state versions. Check --help before you call one directly. Attempts explains the workflow.

Command	What it does
pst pstdio-planner implementation-policy	Shows the project’s implementation options.
pst pstdio-planner implementation-targets	Lists the remote branches you can choose as the default target.
pst pstdio-planner set-implementation-target --branch <branch>	Sets the default target branch. Leave out --branch to clear it.
pst pstdio-planner run-attempt --ticket <ticket>	Starts a managed attempt in a new Git worktree.
pst pstdio-planner attempt-readiness --ticket <ticket>	Checks whether an attempt can start, and from which commit.
pst pstdio-planner submit-change-request	Hands in a revision with its change request report.
pst pstdio-planner run-review	Starts a review of an attempt’s latest revision.
pst pstdio-planner submit-review	Records a review verdict and its threads.
pst pstdio-planner add-review-comment	Adds a comment to a review thread.
pst pstdio-planner resolve-review-thread	Marks a review thread as resolved.
pst pstdio-planner dismiss-review	Dismisses a review, with a reason.
pst pstdio-planner read-review-thread	Reads one review thread.
pst pstdio-planner read-attempt-history	Reads the history of an attempt.
pst pstdio-planner list-attempts	Lists the project’s attempts.
pst pstdio-planner select-attempt	Chooses which attempt of a ticket later tickets build on.
pst pstdio-planner reconcile-attempt	Recovers an attempt whose session disconnected.
pst pstdio-planner request-human	Sets the Review Needed flag with a question for a person.
pst pstdio-planner resolve-human-request	Answers a request and clears the flag when none are left.
pst pstdio-planner migrate-ticket-identities	Gives every ticket a new ID from the project’s ID sequence. See below.

migrate-ticket-identities runs once per project. It first copies .pstdio/tickets to .pstdio/ticket-identity-migration, then rewrites the local ticket files and the ticket links on sessions. Its result lists the workspaces you may need to clean up by hand.

implementation-targets lists the remote branches in the project’s Git folder, one row per branch. It returns an empty list when the project has no local Git folder. The Default target branch dropdown on the Planner extension page loads the same rows.

[{ "branch": "origin/main" }, { "branch": "origin/release" }]

set-implementation-target saves one of those branches and rejects any other name. Run it without --branch to use the repository default branch again. implementation-policy returns the saved branch as defaultTargetBranch.