Prompt registry

Store, version, and promote prompts through a reviewable lifecycle — the same way you manage code.

The prompt registry is a folder of YAML files that track every version of every prompt in your project. Because prompts live in files, every change is visible in git: diffable, reviewable, and reversible.

Prompt file format

Each prompt is stored as a YAML file in the prompts/ directory. Here is a complete example:

id: summarization
version: 2
status: production
body: |
  You are a summarization assistant.
  Summarize the user input in one sentence.
author: emmanuel
created_at: "2026-03-25T12:00:00Z"
tags: ["core", "summary"]

Field	Description
id	Unique identifier for the prompt, used in CLI commands
version	Integer version number, incremented on each change
status	Current lifecycle stage: draft, staging, or production
body	The prompt text sent to the model
author	Who created or last modified the prompt
created_at	ISO 8601 timestamp
tags	Optional labels for organizing and filtering prompts

The promotion lifecycle

Prompts move through three statuses on the way to production:

1. draft

   The default status for every new prompt. A draft prompt is a work in progress — it can be edited freely and has not been validated yet.

2. staging

   Promote to staging once you want to run evals against the prompt before it goes live. This signals that the prompt is a candidate for production.

3. production

   The active, live version of the prompt. Promote to production after the eval run passes. evalflow reminds you to run evalflow eval before this step.

evalflow will remind you to run evalflow eval before promoting to production. Skipping this step means you are shipping a prompt without a quality gate check.

CLI workflow

Create

Create a new prompt YAML file in prompts/:

evalflow prompt create summarization

Created prompts/summarization.yaml

The file is created with status: draft, version: 1, and a placeholder body for you to fill in.

List

View all prompts and their current status:

evalflow prompt list

ID             Version  Status      Author   Created
summarization  1        draft       unknown  2026-03-25

Diff

Compare two versions of the same prompt:

evalflow prompt diff summarization 1 2

- You are a helpful assistant.
+ You are a concise summarization assistant.

Use this before promoting to see exactly what changed between versions.

Promote

Move a prompt to the next stage:

evalflow prompt promote summarization --to staging
evalflow prompt promote summarization --to production

summarization promoted to production

The --to flag accepts staging or production.

Why it matters

Prompt changes are often the most impactful changes in an LLM application, but they rarely go through the same review process as code. The prompt registry makes every change:

• Visible in git — prompt edits appear in pull request diffs like any other file change
• Diffable — evalflow prompt diff shows exactly what changed between versions
• Gated — running evalflow eval before promoting connects prompt changes to quality scores
• Auditable — the author, created_at, and version fields give you a history of who changed what and when

Commit your prompts/ directory and .evalflow/ baseline directory to version control. This gives every developer and your CI runner the same prompt versions and the same quality baseline to compare against.