> ## Documentation Index
> Fetch the complete documentation index at: https://emartai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```yaml theme={null}
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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## CLI workflow

<Tabs>
  <Tab title="Create">
    Create a new prompt YAML file in `prompts/`:

    ```bash theme={null}
    evalflow prompt create summarization
    ```

    ```text theme={null}
    Created prompts/summarization.yaml
    ```

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

  <Tab title="List">
    View all prompts and their current status:

    ```bash theme={null}
    evalflow prompt list
    ```

    ```text theme={null}
    ID             Version  Status      Author   Created
    summarization  1        draft       unknown  2026-03-25
    ```
  </Tab>

  <Tab title="Diff">
    Compare two versions of the same prompt:

    ```bash theme={null}
    evalflow prompt diff summarization 1 2
    ```

    ```text theme={null}
    - You are a helpful assistant.
    + You are a concise summarization assistant.
    ```

    Use this before promoting to see exactly what changed between versions.
  </Tab>

  <Tab title="Promote">
    Move a prompt to the next stage:

    ```bash theme={null}
    evalflow prompt promote summarization --to staging
    evalflow prompt promote summarization --to production
    ```

    ```text theme={null}
    summarization promoted to production
    ```

    The `--to` flag accepts `staging` or `production`.
  </Tab>
</Tabs>

## 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

<Tip>
  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.
</Tip>