CLI
Planner provides ticket, status, tag and 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 pstdio.planner list-tickets [--status <status>] [--tags <tag>...] [--parent <ticket>] [--archived] [--draft]
pst pstdio.planner next-tickets [--track <track>] [--status <status>] [--tags <tag>...] [--parent <ticket>]
pst pstdio.planner create-ticket [--title <title>] [--content <markdown>] [--status <status>] [--tags <tag>...] [--parent <ticket>] [--depends-on <ticket>...]
pst pstdio.planner import-tickets --tickets '<JSON array>'
pst pstdio.planner get-ticket --id <ticket>
pst pstdio.planner update-ticket --id <ticket> [options]
pst pstdio.planner archive-ticket --id <ticket>
pst pstdio.planner unarchive-ticket --id <ticket>
pst pstdio.planner delete-ticket --id <ticket>
pst pstdio.planner link-review --id <ticket> --url <url> [--title <title>]
pst pstdio.planner proposal-refined --id <ticket>
pst pstdio.planner implement-ticket --id <ticket> [--agent '{"harnessId":"<agent-id>"}']
pst pstdio.planner cleanup-board [--agent '{"harnessId":"<agent-id>","model":"<model-id>"}']
list-tickets hides drafts and archived tickets. Use --draft or --archived to list only those.
cleanup-board opens a project agent session using the editable cleanup-board prompt template. It asks the agent to review unfinished tickets across all views, reconcile stale statuses and independent blocked reasons using current evidence, and leave tickets with ongoing or unverifiable sessions unchanged. It does not start implementations or archive tickets.
next-tickets queries current work in timeline order. Its tickets list contains launchable or resumable attempts. Its waiting list explains dependencies, incompatible branches, review requests, gates, assignments, and existing attempts. Both lists use the saved Auto Build eligibility filters and the Require merged dependencies setting. While that setting is off, children can build on submitted dependency commits. Eligible filters apply to new work only. The query works while Auto Build is off and never starts work.
Use --track Workbench to restrict the query to that Track option. Track names and IDs are accepted; unknown names fail instead of widening the query. Status, tag, and direct-parent filters combine with the track. Prerequisites outside the selected track still determine readiness. Drafts, archived tickets, and ignored tickets are omitted. The result includes shared implementation capacity, whether Auto Build is enabled, and its current revision for dispatch.
--tags takes tag option names, such as High or Bug, and can be repeated.
create-ticket creates a ticket. When you pass --content, Planner takes the title from its first line and ignores --title.
import-tickets creates up to 1,000 tickets in one call, for example when moving from another tracker. Each entry has a key and a title or content, and can set status, tags, parent, dependsOn and links. parent and dependsOn name another entry’s key or an existing ticket. links lists { "workspace": "<workspace>" } or { "session": "<session-id>" } targets. Planner numbers the tickets together, saves them in a few grouped writes, adds them after the existing tickets in input order, and returns each key’s ticket ID and shorthand. An unknown status, tag, ticket, workspace or session fails the import before anything is saved:
pst pstdio.planner import-tickets --tickets "$(cat tickets.json)"
get-ticket returns the complete stored ticket.
update-ticket can change --content, --status, --tags, --parent, --depends-on, and --blocked-reason. Use --unlink-parent to remove the parent.
Use depends_on links for prerequisite tickets. blocked_reason is for an independent blocker, such as missing credentials. Clear its text with an explicit empty value:
pst pstdio.planner update-ticket --id PS-123 --blocked-reason ''
This keeps the ticket’s dependency links and status. If it is also in the Blocked status, change that status explicitly when the blocker is resolved.
unarchive-ticket makes an archived ticket active again. Its status, tags, order, and content stay the same.
link-review preserves non-GitHub review URLs. GitHub PRs use Related resources → Link resource: paste the PR URL and choose Result for implementation evidence or Context for reference. Existing GitHub links migrate to result relationships when GitHub is enabled; unavailable providers keep their saved URLs.
Agents use pst pstdio.github pull-requests import --url <url>, then pst resources link --from '<ticket ResourceRef JSON>' --to '<returned ResourceRef JSON>' --role result. Removing a relationship leaves the PR on GitHub.
proposal-refined tells people that a proposal ticket is ready for review. Prompt Studio shows a Review proposal notification.
implement-ticket starts the responsible agent with the implement-ticket prompt. The agent discovers current status IDs and updates ticket progress. 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-ticket and update-ticket accept it:
pst pstdio.planner create-ticket --title "Ship the flag" --depends-on PS-12 --depends-on PS-13
pst pstdio.planner update-ticket --id PS-14 --depends-on PS-12
On update-ticket, 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.
Link to a saved document
document-link returns the ticket’s dashboard path as href. Use a ticket shorthand or UUID. Add --file with a stored file name or ID to select that document; omit it to open the ticket body.
pst pstdio.planner document-link --id PS-12
pst pstdio.planner document-link --id PS-12 --file research.md
The path is relative to your dashboard origin. It identifies saved Planner content. A renamed file keeps its link by ID; deleted files are unavailable.
Edit a ticket as a local file
pst pstdio.planner write-ticket --title <title> [--status <status>] [--tags <tag>...] [--user-prompt <text>] [--parent <ticket>]
pst pstdio.planner save-ticket --id <ticket> [--status <status>]
pst pstdio.planner pull-ticket [--id <ticket>] [--force]
pst pstdio.planner list-ticket-files --id <ticket>
pst pstdio.planner list-ticket-templates
pst pstdio.planner apply-ticket-template --id <ticket> --template <template> [--var <key=value>...]
write-ticket creates a draft ticket and writes it to .pstdio/extension-storage/pstdio.planner/tickets/<ticket>/ticket.md in the project folder. Edit that file and any files in its files/ folder, then run save-ticket to store your changes:
pst pstdio.planner write-ticket --title "Fix login" --status Todo --tags High
pst pstdio.planner save-ticket --id PS-12
save-ticket reads the description, tags, parent, dependencies, and files from the local ticket. After saving, it emits tickets.changed with the ticket ID so open views can refresh. Images in files/ (PNG, JPEG, GIF, WebP, and SVG) are stored as ticket attachments and show in the ticket’s file list. Saving an unchanged image keeps the stored copy. Deleting an image locally does not remove its attachment. 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-ticket writes the ticket’s text files and image attachments to files/. Without --id it pulls all active tickets. It keeps existing local files unless you pass --force.
Images with the same name get distinct local filenames. PNG, JPEG, GIF, WebP, and SVG uploads without a matching suffix get one in the checkout. Planner keeps each local image linked to its attachment in image-checkout.json beside ticket.md; keep this file when editing a checkout. Later dashboard uploads keep their own attachments.
apply-ticket-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-ticket afterwards to store the result. list-ticket-templates lists the template names, and list-ticket-files lists the ticket’s files.
Link workspaces and sessions
pst pstdio.planner link --id <ticket> (--workspace <workspace> | --session <session-id>)
pst pstdio.planner unlink --id <ticket> (--workspace <workspace> | --session <session-id>)
pst pstdio.planner ticket-workspaces --id <ticket>
pst pstdio.planner ticket-worktrees-list --id <ticket>
pst pstdio.planner ticket-worktrees-remove-all --id <ticket>
For example, create one Git worktree and link two tickets to it:
pst workspaces create --provider pstdio.worktree
pst pstdio.planner link --id PS-1 --workspace WS-19
pst pstdio.planner link --id PS-2 --workspace WS-19
pst pstdio.planner ticket-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.
Archiving or deleting a ticket deletes linked workspaces once no active ticket uses them and the project setting Delete linked workspaces (tickets.deleteLinkedWorkspaces) is on. The setting is on by default. Deletion removes the worktree, its branch, and any uncommitted changes. The default project workspace and providers without deletion support stay available. Unarchiving restores the ticket, but does not restore deleted workspaces.
Statuses
pst pstdio.planner ticket-status read
pst pstdio.planner ticket-status create --label <label> [--color <color>] [--icon <icon>] [options]
pst pstdio.planner ticket-status update --status-id <status> [options]
pst pstdio.planner ticket-status reorder --status-ids <json>
pst pstdio.planner ticket-status set-default --status <status>
pst pstdio.planner ticket-status delete --status <status>
create and update accept --can-create and --column-actions <json>. Use --no-can-create to turn creation off. Cards can always be dragged between columns. --column-actions takes a JSON list, such as '["archive_all"]' for the Archive all action. update also accepts --label, --color, --icon, and --sort-order.
Archive all selects active tickets in that status in pages of 100 and returns
{ archivedCount }. It changes only archival fields and queues workspace cleanup
for each saved page. A ticket moved to another status before its page is saved is
excluded after rechecking that selection.
pst pstdio.planner ticket-status create --label "Triaging" --color amber
pst pstdio.planner ticket-status update --status-id backlog --label Backlog --color gray --icon status-backlog
pst pstdio.planner ticket-status reorder --status-ids '["backlog","ready","in-progress","blocked","in-review","done"]'
pst pstdio.planner ticket-status set-default --status Todo
pst pstdio.planner ticket-status 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 pstdio.planner ticket-tag read
pst pstdio.planner ticket-tag create --name <name> [--type <single_select|multi_select>]
pst pstdio.planner ticket-tag update --tag-id <tag> [--name <name>] [--type <type>] [--sort-order <number>]
pst pstdio.planner ticket-tag delete --tag <tag>
pst pstdio.planner ticket-tag create-option --tag-id <tag> --name <name> [options]
pst pstdio.planner ticket-tag update-option --tag-id <tag> --option-id <option> [options]
pst pstdio.planner ticket-tag delete-option --tag-id <tag> --option-id <option>
pst pstdio.planner ticket-tag apply-draft --tag-id <tag> [options]
The default type is single_select. The option commands accept --color, --icon, and --description. ticket-tag update-option also accepts --name and --sort-order.
pst pstdio.planner ticket-tag create --name Priority --type single_select
pst pstdio.planner ticket-tag update --tag-id default-priority --sort-order 0
pst pstdio.planner ticket-tag update-option \
--tag-id default-priority \
--option-id default-priority-urgent \
--color red \
--icon flame
pst pstdio.planner ticket-tag 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
Use the full extension namespace for every Planner command. Add --help to inspect its options.
| Command | What it does |
|---|---|
pst pstdio.planner list-tickets |
Lists tickets. |
pst pstdio.planner create-ticket |
Creates a ticket. |
pst pstdio.planner import-tickets |
Creates up to 1,000 tickets with their parents, dependencies and links. |
pst pstdio.planner get-ticket |
Reads a ticket. |
pst pstdio.planner update-ticket |
Updates ticket metadata. |
pst pstdio.planner archive-ticket |
Archives a ticket. |
pst pstdio.planner unarchive-ticket |
Restores an archived ticket. |
pst pstdio.planner delete-ticket |
Permanently deletes a ticket. |
pst pstdio.planner link-review |
Links a review to a ticket. |
pst pstdio.planner proposal-refined |
Records that a proposal has been refined. |
pst pstdio.planner implement-ticket |
Starts ticket implementation. |
pst pstdio.planner write-ticket |
Creates a local ticket checkout. |
pst pstdio.planner save-ticket |
Saves a local ticket checkout. |
pst pstdio.planner pull-ticket |
Refreshes a local ticket checkout. |
pst pstdio.planner list-ticket-files |
Lists ticket files. |
pst pstdio.planner list-ticket-templates |
Lists ticket templates. |
pst pstdio.planner apply-ticket-template |
Applies a ticket template. |
pst pstdio.planner link |
Links a workspace to a ticket. |
pst pstdio.planner unlink |
Unlinks a workspace from a ticket. |
pst pstdio.planner ticket-workspaces |
Lists up to 100 linked workspaces; pass --cursor to continue. |
pst pstdio.planner ticket-worktrees-list |
Lists up to 100 linked Git worktrees; pass --cursor to continue. |
pst pstdio.planner ticket-worktrees-remove-all |
Removes linked Git worktrees. |
pst pstdio.planner ticket-status read |
Lists ticket statuses. |
pst pstdio.planner ticket-status create |
Creates a ticket status. |
pst pstdio.planner ticket-status update |
Updates a ticket status. |
pst pstdio.planner ticket-status reorder |
Reorders ticket statuses. |
pst pstdio.planner ticket-status set-default |
Sets the default ticket status. |
pst pstdio.planner ticket-status delete |
Deletes a ticket status. |
pst pstdio.planner ticket-tag read |
Lists ticket tags. |
pst pstdio.planner ticket-tag create |
Creates a ticket tag. |
pst pstdio.planner ticket-tag update |
Updates a ticket tag. |
pst pstdio.planner ticket-tag delete |
Deletes a ticket tag. |
pst pstdio.planner ticket-tag create-option |
Creates a tag option. |
pst pstdio.planner ticket-tag update-option |
Updates a tag option. |
pst pstdio.planner ticket-tag delete-option |
Deletes a tag option. |
pst pstdio.planner ticket-tag apply-draft |
Applies a tag and option draft. |
Workflow commands
These commands support agents and automations, and their options can include revision IDs, report IDs, and exact commit and revision identities. 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 update-stack |
Integrates the current dependency base in the existing owner workspace. |
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-review |
Asks a person for an unresolved decision and updates the Needs attention count. |
pst pstdio.planner review --request-id <id> --response <JSON> |
Answers a review request. Clears the flag when none are open. |
pst pstdio.planner review-requests list --ticket <ticket> |
Lists a ticket’s review requests. Add --open-only for open ones. |
pst pstdio.planner review-requests read --request-id <id> |
Reads one request with its questions, choices, and outcome. |
pst pstdio.planner review-requests cancel --request-id <id> |
Withdraws an open request. Needs --reason. |
pst pstdio.planner review-requests open --request-id <id> |
Opens the chat linked to a request. |
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.
Ticket cleanup and merge settings
Archiving or deleting a ticket deletes linked workspaces once no active ticket uses them and the project setting Delete linked workspaces (tickets.deleteLinkedWorkspaces) is on. The setting is on by default. Deletion removes the worktree, its branch, and any uncommitted changes. The default project workspace and providers without deletion support stay available. Unarchiving restores the ticket, but does not restore deleted workspaces.
The project setting Mark done on merge (tickets.markDoneOnMerge) is also on by default. Local merges move linked tickets to the selected completed status after merge. Configure that destination in Planner workflow settings. Missing configuration leaves ticket progress unchanged. Planner checks GitHub pull request links and linked workspace branches every five minutes with up to eight parallel checks. Install and authenticate GitHub CLI (gh) on the host for these checks. Failed GitHub checks leave tickets unchanged and log the failure. Merges do not archive tickets or delete workspaces.
Updated at: 2026-11-05