Skip to main content

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.

​
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:
LabelUse
devActive development
stagingPre-production validation
prodProduction prompt

​
Runtime Attribution

Node.js: 
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: 
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.