---
title: 'prompts'
description: 'Manage the versioned prompt catalog of a running agent installation: list, get, create, update, publish, unpublish, remove, remove-version, versions and preview'
position: 23
---

# 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](/docs/cli/reference/conventions#target-resolution).
> `remove`, `remove-version`, `publish` and `unpublish` are
> [destructive verbs](/docs/cli/reference/conventions#destructive-verbs) that
> refuse to run without `--yes`. Every verb emits the shared
> [JSON envelope](/docs/cli/reference/conventions#json-output) 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`](/docs/sdk/platform/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**

```jsonc
// 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`](/docs/sdk/platform/prompts#compileowner-key-vars-options),
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`).