Full reference

Versioned prompts

Give a prompt a stable key, create immutable versions, and move labels only when you intend callers to use a different version.

Updated

Reviewed against Console v0.2.2. Available actions depend on project access and runtime configuration; check your installed CLI version for command differences.

Inspect versions in Lab → Prompts

  1. Choose the project, then open Lab → Prompts.
  2. Find your prompt and compare Live, Latest, Versions, and Updated in the list. Open the prompt to inspect its version history.
  3. Use actual registered key/version/label values when attaching lineage to requests. Do not copy illustrative metadata and call it production lineage.
  4. Compare a candidate through Lab → New evaluation → Prompt. Check the current text and diff before execution.

A new version does not move the production label by itself. Applying a live prompt change affects callers that resolve that label. For automatic diagnosis, Improve needs captured evidence tied to the real production prompt.

Inspect a prompt

bash
stimulir prompts list
stimulir prompts versions support.summary
stimulir prompts get support.summary --label prod

A key names the prompt; a version identifies exact content; a label points to a selected version. Use the specific version when reproducibility matters.

Create a version from a file

bash
stimulir prompts create --key support.summary --file prompt.txt --notes "Candidate revision"

Inspect the returned version before attaching a production label. Metadata updates do not edit immutable prompt content.

Render and record lineage

python
prompt = client.prompts.get("support.summary", label="prod")
text = prompt.render({"request": "Example request"})
reply = client.agent(
    prompt=text, model="<enabled-model-id>", tag="summary", metadata=prompt.lineage
)

Initialize client with the intended application key and project as shown in the Python SDK. Match template variable names and keep prompt lineage with inference evidence.

Move a label

bash
stimulir prompts label support.summary <version> prod

This changes what label-based consumers resolve next. Review the target version and affected applications first. The same operation can move a label back to a previously reviewed version.

Evaluate before production

Compare the candidate against the incumbent on the same snapshot and evaluator. A favorable individual example is not enough to change a shared label. Use Evaluation or Improve, then make the promotion decision separately.

Command catalogue

Expand a command for its arguments. These commands follow the released CLI source; check stimulir --version and the command’s --help for your installation. Required flags are marked; some operations also validate combinations of inputs.

stimulir prompts archive

Archive a prompt version by marking it inactive.

key required
Positional argument. Prompt key.
version required
Positional argument. Version number to archive.
--json
Emit raw JSON output.
stimulir prompts create

Create a prompt (or a new version of an existing key).

--key, -k required
Stable prompt key.
--content
Prompt body (or use --file / stdin).
--file, -f
Read prompt body from this file.
--name
Display name.
--type
Optional prompt type tag.
--label
Label to attach to this version (e.g. prod).
--notes
Change notes for this version.
--json
Emit raw JSON output.
stimulir prompts get

Fetch a prompt by key plus label/version.

key required
Positional argument. Prompt key.
--label
Label to fetch, e.g. prod or staging.
--version
Specific version to fetch.
--json
Emit raw JSON output.
stimulir prompts label

Move a label to a specific version (promote or roll back).

key required
Positional argument. Prompt key.
version required
Positional argument. Version number to label.
label required
Positional argument. Label to set on this version.
--json
Emit raw JSON output.
stimulir prompts list

List versioned prompts in the active workspace.

--json
Emit raw JSON output.
stimulir prompts update

Update prompt metadata. Prompt content remains immutable; create a new version to edit content.

key required
Positional argument. Prompt key.
version required
Positional argument. Version number to update.
--name
Display name.
--notes
Change notes.
--active/--inactive
Mark this version active or inactive.
--json
Emit raw JSON output.
stimulir prompts versions

Show the full version history for a prompt.

key required
Positional argument. Prompt key (from stimulir prompts list).
--json
Emit raw JSON output.

SDK method catalogue

Expand a client to inspect public methods and parameter names. Read each operation’s task guide before supplying a payload or starting work. The SDK returns platform responses; handle errors and inspect completion state before using a result.

client.promptsPromptsClient
list(active_only)
Returns the platform response; inspect its status and error detail.
get(key, label, version)
Returns the platform response; inspect its status and error detail.
versions(key)
Returns the platform response; inspect its status and error detail.
create_version(key, content, name, prompt_type, variables, label, tags, change_notes)
Returns the platform response; inspect its status and error detail.
label(key, version, label)
Returns the platform response; inspect its status and error detail.
patch_metadata(key, version)
Returns the platform response; inspect its status and error detail.
archive(key, version)
Returns the platform response; inspect its status and error detail.