Skip to main content

​
MutagenT CLI

The MutagenT CLI (mutagent) is the AI-native, CLI-first developer interface for the MutagenT platform. It provides full access to prompt management, datasets, evaluations, optimization, tracing, playground execution, and framework integrations — all from your terminal.
AI Agent Friendly - Every command supports --json for structured output with _links to the web UI at app.mutagent.io. Use --help on any command for progressive disclosure. Built-in workflow guidance and AI agent integration hints are shown in top-level help.

​
Why CLI First?

AI Agent Integration

Designed for Claude Code and other AI assistants. Built-in integration hints in --help output, --json with _links for navigation, and mutagent integrate for framework-specific SDK code.

Progressive Disclosure

Every command and subcommand supports --help with examples. AI agents can discover capabilities incrementally without reading docs.

JSON Output

All commands support --json for machine-readable output. JSON responses include _links with deep links to app.mutagent.io for easy navigation.

CI/CD Ready

--non-interactive flag disables all prompts. Also auto-enabled when CI=true env var is set or stdin is not a TTY. Pair with --api-key for pipeline use.

​
Architecture

​
Command Structure

mutagent <command> [subcommand] [options]

​
Top-Level Commands

CommandDescription
mutagent loginQuick login (alias for auth login)
mutagent authAuthentication management (login, logout, status)
mutagent configConfiguration persistence (set, get, list)
mutagent initInitialize project (.mutagentrc.json wizard)
mutagent promptsPrompt CRUD, datasets, evaluations, optimization
mutagent tracesTrace viewing, analysis, and export
mutagent integrateGenerate framework-specific SDK integration code
mutagent playgroundExecute and test prompts with streaming support
mutagent agentsAgent CRUD (list, get, create, update, delete)
mutagent workspacesView workspace details
mutagent providersView and test LLM providers
mutagent exploreScan codebase for prompts, datasets, and markers
mutagent skillsInstall MutagenT CLI skill for coding agents
mutagent hooksHook handlers for AI coding assistant telemetry (Claude Code)
mutagent usageShow resource counts and plan limits

​
Prompt Subcommands

The prompts command contains nested command groups for the full evaluate-optimize workflow:
SubcommandDescription
prompts list / get / create / update / deletePrompt CRUD
prompts create --output-schemaStructured output schema (required for optimization)
prompts dataset list / add / deleteDataset management (inline -d JSON)
prompts evaluation list / get / create / deleteEvaluation criteria management
prompts evaluation create --guidedInteractive criteria builder
prompts optimize start / status / resultsOptimization with --max-iterations, --target-score, --model

​
Global Options

OptionDescription
--jsonOutput results as JSON (for AI agents and automation)
--non-interactiveDisable all interactive prompts (also enabled by CI=true or non-TTY stdin)
--api-key <key>Override API key for this command
--endpoint <url>Override API endpoint
--helpShow help for any command (includes examples and workflow hints)
-v, --versionShow CLI version

​
Quick Start

bun add -g @mutagent/cli

# Authenticate (interactive - choose browser OAuth or API key)
mutagent auth login

# Or use browser OAuth directly
mutagent auth login --browser

# Set default workspace for zero-config commands
mutagent config set workspace <workspace-id>

# List your prompts
mutagent prompts list

# Test a prompt in the playground
mutagent playground run <prompt-id> --input '{"name": "John"}'

# Get integration code for your framework
mutagent integrate langchain

​
Post-Onboarding Flow

After mutagent auth login succeeds, the CLI presents three paths to get started: Path A: Guided Integration — Connect your AI framework (Mastra, LangChain, Vercel AI, etc.) with auto-generated SDK integration code. The CLI scans your codebase, detects your framework, and produces ready-to-use tracing and optimization wrappers. Path B: Quick Optimization — Upload a prompt and optimize it immediately. The CLI walks you through creating a prompt, adding evaluation criteria, uploading a dataset, and running an optimization — all in one guided flow. Path C: Exit — Skip the guided flow and explore on your own using mutagent --help or the docs.
You can always re-enter the guided flows later. Run mutagent explore to scan your codebase, or jump directly into any command.

​
Evaluate-Optimize Workflow

The CLI includes built-in workflow guidance in its --help output. The core loop is: 
# 1. Create a prompt with structured output (--data is preferred for AI agents)
mutagent prompts create --name "My Prompt" --system "..." --human "{input}" --output-schema '{"type":"object","properties":{"result":{"type":"string"}}}'

# 2. Upload a dataset
mutagent prompts dataset add <prompt-id> --name "Training Data" --file data.json

# 3. Define evaluation criteria (interactive guided mode OR file)
mutagent prompts evaluation create <prompt-id> --guided
# OR
mutagent prompts evaluation create <prompt-id> --name "Quality" --file criteria.json

# 4. Run optimization
mutagent prompts optimize start <prompt-id> --dataset <id> --max-iterations 3

# 5. Review results (shows scorecard with before/after comparison)
mutagent prompts optimize results <job-id>
Provider setup required: Optimization requires at least one LLM provider to be configured. Set up providers at app.mutagent.io/settings/providers or verify with mutagent providers list. The server will return an error if no provider is available when starting an optimization.

​
For AI Agents

When working with AI coding assistants like Claude Code: 
# Zero-config with environment variables
export MUTAGENT_API_KEY="mt_your_key_here"

# Discover available commands (includes workflow guidance and integration hints)
mutagent --help

# Get detailed help for a specific command
mutagent prompts --help
mutagent prompts optimize --help

# Get JSON output for parsing (includes _links with deep links to app.mutagent.io)
mutagent prompts list --json
mutagent prompts get <id> --json

# Non-interactive mode for automation
mutagent prompts list --non-interactive

# Generate SDK integration code (supports --raw for code-only output)
mutagent integrate langchain --raw

# Supported frameworks
mutagent integrate langchain
mutagent integrate langgraph
mutagent integrate vercel-ai
mutagent integrate openai

# Verify an integration setup
mutagent integrate langchain --verify

# Stream prompt execution
mutagent playground run <prompt-id> --input '{}' --stream --json
Set MUTAGENT_API_KEY environment variable for zero-config usage. The CLI picks it up automatically — no auth login step required. You can also pass --api-key inline for one-off commands. Setting CI=true or piping stdin enables non-interactive mode automatically.

​
State Tracking

The CLI maintains local state to track your MutagenT workflow:
ArtifactPurpose
.mutagent/mutation-context.mdLocal context file tracking discovered prompts, uploaded resources, and optimization history
MutagenT:START / MutagenT:END markersComment markers in source files identifying managed prompts
mutagent auth statusShows onboarding state, context file status, and resource counts
# Scan codebase and populate context file
mutagent explore

# Check your current state
mutagent auth status

# Install Claude Code skill for AI agent guidance
mutagent skills install

​
Key Behaviors

  • Template variable syntax: MutagenT uses {variable} single-brace syntax. The CLI warns if it detects double-brace {{variable}} patterns in prompt content.
  • Dataset formats: prompts dataset add accepts JSON arrays, JSONL (auto-detected), and CSV files. Inline data is supported via -d flag.
  • Streaming: playground run --stream streams tokens via SSE. In --json mode, each token is emitted as a separate JSON object.
  • Error masking: SDK errors are translated into clean, actionable user-facing messages with hints for resolution.
  • Config persistence: config set workspace <id> and config set org <id> persist defaults so you don’t need to specify them on every command.
  • --data flag: Agent and dataset commands accept -d, --data <json> for curl-style inline JSON input. This is the recommended method for AI agents and CI/CD pipelines.
  • Output schema enforcement: outputSchema is required for prompt creation when optimization is planned. Provide via --data, --file, or --output-schema. In interactive mode, you will be prompted if missing.
  • Mutation context: mutagent explore scans your codebase and stores findings in .mutagent/mutation-context.md. Other CLI commands auto-update this context file after create/update operations.
  • Optimization scorecard: mutagent prompts optimize results now shows a scorecard with before/after comparison, score progression across iterations, and an interactive apply/reject flow.

​
What’s Next

Installation

Install and configure the CLI

Commands

Full command reference

Integrations

Generate framework integration code