Skip to main content
Running Prompts Run prompts from the command line for quick testing or programmatically in your application.

​
CLI Usage

​
Quick Start

npm run prompt agentmark/greeting.prompt.mdx
Requirements:
  • Prompt file created (.prompt.mdx)
  • Development server running (npm run dev)

​
Passing Props

Inline JSON: 
npm run prompt agentmark/greeting.prompt.mdx \
  --props '{"name": "Alice", "role": "developer"}'
From file: 
npm run prompt agentmark/greeting.prompt.mdx \
  --props-file ./test-data.json

​
Output Examples

Text generation: 
$ npm run prompt agentmark/story.prompt.mdx

=== Text Prompt Results ===
Once upon a time...

────────────────────────────────────────────────────────────
🪙 250 in, 100 out, 350 total
Object generation: 
$ npm run prompt agentmark/extract-data.prompt.mdx

=== Object Prompt Results ===
{
  "name": "John Smith",
  "email": "[email protected]"
}

────────────────────────────────────────────────────────────
🪙 180 in, 45 out, 225 total
Image & audio generation: Generated media files are saved to .agentmark-outputs/: 
$ npm run prompt agentmark/logo.prompt.mdx

=== Image Prompt Results ===
Saved 2 image(s) to:
- .agentmark-outputs/image-1-1698765432.png
- .agentmark-outputs/image-2-1698765432.png

​
SDK Usage

AgentMark works with multiple AI SDKs through adapters. Examples below use Vercel AI SDK, but the pattern is the same for all adapters.

​
Text Generation

import { client } from './agentmark.client';
import { generateText } from 'ai';  // Vercel AI SDK

// Load prompt and format with props
const prompt = await client.loadTextPrompt('agentmark/greeting.prompt.mdx');
const input = await prompt.format({
  props: {
    name: 'Alice',
    role: 'developer'
  }
});

// Pass to your AI SDK's generation function
const result = await generateText(input);
console.log(result.text);
// Output: "Hello Alice, welcome to the developer portal!"

​
Object Generation

import { client } from './agentmark.client';
import { generateObject } from 'ai';  // Vercel AI SDK

// Load prompt and format with props
const prompt = await client.loadObjectPrompt('agentmark/extract-data.prompt.mdx');
const input = await prompt.format({
  props: {
    input: 'Contact John Smith at [email protected]'
  }
});

// Pass to your AI SDK's generation function
const result = await generateObject(input);
console.log(result.object);
// Output: { name: "John Smith", email: "[email protected]" }
Note: Different adapters may have different function names. Vercel AI SDK uses generateObject, Mastra uses agent.generate(), etc.

​
Image Generation

import { client } from './agentmark.client';
import { experimental_generateImage } from 'ai';  // Vercel AI SDK

// Load prompt and format with props
const prompt = await client.loadImagePrompt('agentmark/logo.prompt.mdx');
const input = await prompt.format({
  props: {
    company: 'Acme Corp',
    style: 'modern'
  }
});

// Pass to your AI SDK's image generation function
const result = await experimental_generateImage(input);

// Save images
result.images.forEach((image, i) => {
  fs.writeFileSync(`logo-${i}.png`, image.data);
});

​
Audio Generation

import { client } from './agentmark.client';
import { experimental_generateSpeech } from 'ai';  // Vercel AI SDK

// Load prompt and format with props
const prompt = await client.loadAudioPrompt('agentmark/narration.prompt.mdx');
const input = await prompt.format({
  props: {
    script: 'Welcome to our podcast'
  }
});

// Pass to your AI SDK's audio generation function
const result = await experimental_generateSpeech(input);

// Save audio
fs.writeFileSync('narration.mp3', result.audio);

​
Using Other Adapters

The pattern is always the same:
  1. Load prompt with client.loadTextPrompt() / loadObjectPrompt() / etc.
  2. Format with props: await prompt.format({ props: {...} })
  3. Pass to your adapter’s generation function
Vercel AI SDK: generateText(), generateObject() Mastra: agent.generate() or similar Custom: Your own generation function Learn more about adapters →

​
Development Workflow

​
CLI Development

1. Start dev server - Run npm run dev in one terminal 2. Create/edit prompt - Write your .prompt.mdx file 3. Test with CLI - Run npm run prompt to see output 4. Iterate - Edit prompt, re-run command (auto-reloads)

​
SDK Integration

1. Import SDK - Add @agentmark/sdk to your project 2. Load prompt - Use appropriate loader for generation type 3. Run with props - Pass dynamic data to your prompt 4. Handle results - Process text, objects, images, or audio

​
When to Use Each

Use CLI when:
  • Quick testing during development
  • Iterating on prompt design
  • Debugging prompt behavior
  • Manual verification
Use SDK when:
  • Integrating prompts into your application
  • Building production features
  • Automated workflows
  • Dynamic runtime execution

​
Troubleshooting

​
CLI Issues

Server connection error:
  • Ensure npm run dev is running
  • Check ports 9417 and 9418 are available
File not found:
  • Verify file path is correct
  • Ensure file has .prompt.mdx extension
Invalid JSON in props:
  • Use valid JSON with double quotes
  • Escape quotes in shell: '{\"key\":\"value\"}'

​
SDK Issues

Module not found:
  • Install SDK: npm install @agentmark/sdk
  • Check import path is correct
Prompt not loading:
  • Verify prompt file exists
  • Check file path is relative to project root
Type errors:
  • Ensure you’re using the correct loader for your prompt type
  • Use TypeScript for better type safety

​
Next Steps

Running Experiments

Test prompts with datasets

Generation Types

Text, objects, images, and audio

Integrations

Vercel, Mastra, and more