Projects
A project is a folder that Prompt Studio opens with its own tools, settings, data, and workspaces. These commands create, list, inspect, and remove projects.
pst projects create [name] [--path <folder>]
pst projects list [--cloud]
pst projects view [--project-id <project-id>]
pst projects delete <project-id>
pst projects delete-local <project-id> [--discard-unsynced] # unreleased
pst projects download <project-id> # unreleased
pst projects delete-cloud <project-id> --confirm # unreleased
pst projects deletion-status <project-id> # unreleased
pst projects environment # from the release after 0.43.x
pst projects bind <project-id> --environment <environment-id> --name <name> --path <folder> # from the release after 0.43.x
pst projects recovery-points <project-id> # on main
pst projects restore <project-id> --hours <1|12|24> --captured-at <time> [--extension-id <extension-id>] # on main
pst projects returned-changes <project-id> [apply|discard|dismiss] # unreleased
pst projects folder sources <project-id> # unreleased
pst projects folder status <project-id> # unreleased
pst projects folder capture <project-id> # unreleased
pst projects folder download <project-id> --device <device-id> --source <source-id> [--no-wait] # unreleased
pst projects folder restore <project-id> --device <device-id> --source <source-id> --path <new-folder> [--no-wait] # unreleased
pst projects folder cancel <project-id> # unreleased
create uses the current directory and its folder name unless you pass --path or a name. Git is optional. Numeric and Unicode folder names work. Choosing the same folder again, including through a symlink, opens its existing project. Choosing a child folder creates a separate project, even inside a Git repository.
pst projects create --path ./notes
pst projects create "My tools" --path ./tools
The runtime writes .pstdio/config.json in the folder, sets up the default extensions, and creates the default workspace. Sessions in that workspace share the folder. You can rename the project in its settings.
Commands find the project from the nearest .pstdio/config.json in the current folder or a parent folder. They do not move up to a containing Git root. The project’s default workspace decides where its files are, even when an old config file exists elsewhere. A folder with this file is a linked project. Commands that act on a project, such as pst extensions add and pst workspaces, need one.
delete removes the project from Prompt Studio. The folder and its contents stay on disk. Resources that a workspace provider created follow that provider’s deletion rules.
Use list --cloud to see this device’s project presence and outstanding deletion receipts as JSON. A Cloud only entry takes an explicit download to restore. Catalog and status commands only read existing state.
delete-local removes this device’s downloaded data and keeps the project available from Cloud. The source folder and other devices’ copies stay in place. If uploads are pending or the device cannot verify completion, including when offline, pass --discard-unsynced to accept possible loss. The host rechecks before removal. Repeat the command to finish interrupted cleanup.
download requires a connection to Cloud and prints whether the download is in progress or ready. The host prepares the project folder after the copy becomes ready.
delete-cloud --confirm retires the Cloud project permanently. Downloaded copies remain available as local projects, including edits made offline. projects local (Make local) stops sync and keeps the shared identity available for a later merge. The deletion command prints the affected scope to stderr and an operation receipt to stdout. A receipt in state deleting or needs-attention represents unfinished cleanup. If the start reply is lost, run deletion-status when connected. Repeating confirmed deletion resumes the operation with the same ID. The Cloud catalog can show cached receipts offline.
Run pst projects <command> --help for current options.
environment and bind are on main and ship in the release after 0.43.x. The 0.43.x CLI does not have them.
environment prints this runtime’s stable environment ID as JSON. bind associates a known workbench (project) ID with an existing folder in that environment. Pass the ID returned by environment to select the target explicitly. The command preserves existing bindings and prints the resulting local workspace as JSON. It does not grant cloud access or start synchronization. Existing local projects stay independent.
recovery-points and restore are on main and first ship in 0.46.0. recovery-points prints this device’s recovery points for a cloud project as JSON, with each point’s period, capture time and restorable extensions. restore writes the difference to one of those points as a normal edit, so it syncs to your other devices. Pass the exact capturedAt from the list. See Restore project data.
returned-changes is unreleased. Without an action it lists the changes this device made while signed out of a cloud project’s account, and this device’s changes that Cloud replaced because another device changed them first. A large return after signing out waits on this device: apply uploads it, keeping fields other devices changed meanwhile, and discard drops it and shows Cloud’s copy. dismiss clears the replaced list. See ADR 0139.
projects folder is unreleased and works on macOS and Linux. It recovers a cloud project’s folder from a copy that one of your devices captured, without a Git host or the source device online. Each device whose folder has a root .pstignore captures it under that file and uploads an encrypted copy; a folder without one is not copied. Your other devices download every completed copy automatically.
sourcesprints the copies as JSON: device, source, original folder, capture times, included files and bytes, the applied.pstignore, Git state, and whether every byte is already on this device (available).restorecreates the new folder. The path must not exist, not even as an empty folder, and its parent must exist. The copy is downloaded first if needed, written into a hidden sibling staging folder, verified and then moved into place with a rename that refuses an existing folder. If something creates the folder meanwhile, the restore fails and that folder stays unchanged. The restored folder becomes the project’s folder through the normal attach flow, unless the project already has a folder on this device. A relative--pathis resolved from your current folder. Restored hooks, scripts and automations are not run, and the folder’s own extensions stay disabled until you enable them. Working Git administration that lived outside the source folder is rebuilt under.pstdio/recovery/, which Git ignores. Git links to administration that was not restored are left out, so the restored folder never changes another repository on this computer. Restored files keep permission bits only. A restored folder that became the project’s folder is captured at once and uploaded as this device’s own copy when it has a root.pstignore(copies taken before PS-1130 may restore without one and are then not copied again); the source device’s copy stays listed and restorable.downloadandrestorewait and print progress to stderr, then print the same JSON asstatusand the project’s sync status. A failed or cancelled operation exits with status 1 and prints its error code and message. Ctrl-C cancels it and removes only its staging folder. Pass--no-waitto return immediately.capturecaptures this device’s folder now.cancelstops a running download or restore.
The device must have connected to Cloud once since Prompt Studio started, so it can unlock its private copies.
Cloud JSON listing retains account and membershipKnown. When membershipKnown is false, presence: "unknown" on a locally listed copy means its Cloud membership has not been established; empty Cloud/deletion arrays are incomplete. delete-cloud --confirm requires a signed-in catalog account and pins the deletion to it.
Updated at: 2026-11-19