stackbone prompts

stackbone prompts targets a running agent installation. With no --agent it runs against the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. remove, remove-version, publish and unpublish are destructive verbs that refuse to run without --yes. Every verb emits the shared JSON envelope under --json.

Manage the versioned, named-by-key prompt catalog on the targeted installation. Writing and publishing are two steps. Each key holds an append-only chain of immutable versions and exactly one of them is PUBLISHED — the one the agent reads. update writes a version that does not run yet; publish points the prompt at a version that already exists, so going back to v3 makes the prompt read v3 rather than a copy of its text under a new number. What is published cannot be deleted — neither the version nor the prompt holding it — until you unpublish. This is the catalog the agent reads at runtime through stackbone.prompts.

Command	Purpose
stackbone prompts list	List every prompt at its published version (up to 200, ordered by key).
stackbone prompts get <key>	Print a prompt (the published version, or a pinned --version <n>).
stackbone prompts create <key>	Register a prompt at version 1, published. Content via --template, --file or stdin; --name required.
stackbone prompts update <key>	Write a version and/or patch the head. The new version does NOT run until publish.
stackbone prompts publish <key> --version <n>	Make an existing version the one the agent runs. Points at it — nothing is copied. Requires --yes.
stackbone prompts unpublish <key>	Take the prompt out of service. History stays; nothing runs until you publish again. Requires --yes.
stackbone prompts versions <key>	List a prompt's version history (newest first, up to 200), marking the published one.
stackbone prompts remove-version <key> --version <n>	Delete one version from the history. Refused for the published one. Requires --yes.
stackbone prompts remove <key>	Soft-delete a prompt. Refused while it publishes a version — unpublish first. Requires --yes.
stackbone prompts preview <key>	Server-side compile the prompt against a --vars <file.json>; reports a missing {{var}} cleanly.

JSON payload

// prompts list
{ "schema_version": 1, "items": [{ "key": "welcome_email", "publishedVersion": 3, "name": "Welcome email" }] }

// prompts preview: a missing variable is a clean result, not an error
{ "schema_version": 1, "ok": true, "version": 3, "output": "Hi Ada", "missingVar": null }

// the same call when {{name}} has no value: ok is false, output is null
{ "schema_version": 1, "ok": false, "version": 3, "output": null, "missingVar": "name" }

A prompt key is workspace-unique and URL-safe: lowercase, starting with a letter, then letters, digits, _ or -, up to 128 characters (welcome_email, tool-describe-orders). Content is capped at 256 KiB.

--template and --file are mutually exclusive. On update, pass at least one field. create also takes an optional --description and --metadata. Like get, preview accepts a pinned --version <n> and compiles the current version when you omit it.

A template uses the {{var}} Mustache subset only: no conditionals, no loops, no helpers. That is the same engine the agent compiles with through stackbone.prompts.compile, so a preview here matches what the agent renders.

Exit codes: 0 ok · 4 not found (unknown key/version) · 5 permission (remove/remove-version/publish/unpublish without --yes) · 1 generic (missing --name/content, bad --metadata JSON, unreadable --file/--vars, non-integer --version).