Skip to main content

​
1. Initialize Moda

moda init
moda init authenticates the CLI, writes SDK setup guidance, and creates a prompt manifest:
.moda/prompts.yml
version: 1
prompt_paths:
  - "prompts/**/*.prompt.md"
  - "prompts/**/*.prompt.json"
  - "prompts/**/*.prompt.yaml"
  - "prompts/**/*.prompt.yml"

​
2. Add a Prompt File

prompts/support/triage.prompt.md
---
key: support.triage
name: Support triage
system_prompt: You route support tickets to the right team.
model: gpt-4o
---
Ticket:
{{ticket.text}}

​
3. Check Status

moda prompts status
The command prints JSON showing new, changed, unchanged, and deleted prompt files.

​
4. Sync Versions

moda prompts sync
Sync uploads changed prompts and writes .moda/prompts.lock.json with the server prompt ID, version ID, source path, and content hash. During development, you can keep the sync loop running: 
moda prompts sync --watch

​
5. Render at Runtime

import { Moda } from "moda-ai";
import OpenAI from "openai";

await Moda.init(process.env.MODA_API_KEY!);

const client = new OpenAI();
const rendered = Moda.prompt("support.triage").render({
  ticket: { text: userMessage },
});

Moda.conversationId = conversationId;
Moda.userId = userId;

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: rendered.messages,
});

await Moda.flush();

​
6. Promote a Label

moda prompts promote support.triage --label=prod --version=pver_abc123
Use dev, staging, and prod labels to mark rollout state. Versions stay immutable; labels move.