Skip to main content
Moda prompt management is code-first: prompt files live in your repository, and the moda CLI syncs them to a versioned registry. Use it to keep an immutable history of every prompt change, mark which version is released where, and see how each version behaves in production.

​
How it works

  1. Prompt files (.prompt.md or .prompt.json) live in your repo. A manifest at .moda/prompts.yml declares where to find them.
  2. moda prompts sync uploads them to the registry. Each unique content gets an immutable, content-addressed version.
  3. Release labels (dev, staging, prod) point at versions. Promoting moves a label; it never changes content.
  4. At runtime, your application stamps prompt identifiers on its LLM calls so Moda can attribute traces to versions. See Prompt attribution.
The Moda SDKs do not include a prompt fetch, render, or templating API. Your application loads prompt content the same way it does today — from source files, constants, or your own loader. Moda versions the files and attributes runtime calls; it is not in the request path.

​
Versions are content-addressed and immutable

A version’s identity is a hash of the prompt’s key and content: the prompt text, system prompt, messages, variables, variables schema, model config, tool references, and response schema. This means:
  • Syncing unchanged content is a no-op that returns the same version ID. Retries and repeated CI runs never create duplicate versions.
  • Any content change creates a new version. Existing versions are never modified.
  • Changing only name, description, or category does not create a new version.
  • There is no delete or archive operation. Deleting a local file removes it from your lockfile on the next sync, but the prompt and its versions remain in the registry.
Version IDs look like pver_0f31c2ab9d4e8877a1b2c3d4e5f60718; prompt IDs look like prompt_7d1a9c0b3e5f24681357ace9. Both are recorded in .moda/prompts.lock.json after a sync.

​
Release labels

A label points at exactly one version of a prompt. Promoting moves the label from whichever version held it to the target version.
Promoting a version to dev is overwritten by the next sync, because sync always moves the dev label to the version it just uploaded. Use staging or prod for pins that should survive syncs.
Release labels are release pointers in the prompt registry. They are unrelated to the environment field (development / staging / production) on ingested traces.

​
Prompts in the dashboard

Open Dashboard → Prompts (in the Improve group). The library page lists repository-synced prompts with their versions, release labels, call counts, and candidates awaiting review. Filter tabs narrow the list by label: All, Prod, Staging, Dev, Unlabeled. Each prompt’s detail page shows the key, its labels, the source path, source commit, and manifest hash, plus two tabs:
  • Versions — every synced version with its content, buttons to promote a version to staging or prod, a release-label panel showing which version each label points at, and a runtime usage table (calls, traces, input and output tokens per version). Usage rows appear only for calls that carry prompt attribution.
  • Optimize — candidates awaiting review (unlabeled versions generated by moda prompts propose, plus proposals saved from the Playground), a history of comparison runs, and links into the Playground. Nothing on this tab deploys automatically: merging a candidate creates an unlabeled version that you promote explicitly.
The Open in Playground button starts an interactive comparison of the prompt’s production content against an edited candidate. See Prompt experiments.

​
Next steps