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

# Prompt Management

> Code-first prompt versioning, runtime attribution, and dashboard visibility

## Overview

Moda prompt management keeps prompts in your repository and syncs immutable versions to Moda. Developers edit prompt files, the CLI detects local changes, `moda prompts sync` uploads new versions, and the dashboard shows each prompt, version, source path, labels, and runtime usage.

This is designed for evals: every LLM call can carry `moda.prompt_key`, `moda.prompt_id`, `moda.prompt_version`, and `moda.prompt_version_id`, so later eval runs can compare prompt versions against production behavior.

## Workflow

1. Run `moda init` once in the repo.
2. Keep prompt files under `prompts/**/*.prompt.md` or `prompts/**/*.prompt.json`.
3. Check local changes with `moda prompts status`.
4. Upload immutable versions with `moda prompts sync`.
5. Render prompts at runtime with `Moda.prompt(...).render(...)` or `moda.prompt(...).render(...)`.
6. Promote labels with `moda prompts promote <key> --label=prod --version=<version_id>`.

## Versioning

Each prompt version is content-addressed from the prompt key, content, messages, system prompt, model config, variables schema, tools, and response schema. Syncing unchanged content reuses the same version; changing a prompt creates a new version.

Labels are pointers:

| Label     | Use                       |
| --------- | ------------------------- |
| `dev`     | Active development        |
| `staging` | Pre-production validation |
| `prod`    | Production prompt         |

## Runtime Attribution

Node.js:

```typescript theme={"dark"}
const rendered = Moda.prompt("support.triage").render({
  ticket: { text: userMessage },
});

await Moda.withPrompt(rendered, async () => {
  await openai.chat.completions.create({
    model: "gpt-4o",
    messages: rendered.messages,
  });
});
```

Python:

```python theme={"dark"}
rendered = moda.prompt("support.triage").render({
    "ticket": {"text": user_message},
})

client.chat.completions.create(
    model="gpt-4o",
    messages=rendered["messages"],
)
```

The SDKs attach prompt metadata to OpenTelemetry spans. Moda ingest stores that metadata with conversation logs, making prompt usage visible in the dashboard and queryable for future evals.

## Dashboard

The Prompts dashboard shows synced prompts and versions from the backend registry. Use it to inspect source paths, labels, content hashes, and usage. Treat the repository as the source of truth; use the dashboard for visibility and promotion, not copy-pasting prompt text into code.