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

Command	Description
`mutagent login`	Quick login (alias for `auth login`)
`mutagent auth`	Authentication management (login, logout, status)
`mutagent config`	Configuration persistence (set, get, list)
`mutagent init`	Initialize project (`.mutagentrc.json` wizard)
`mutagent prompts`	Prompt CRUD, datasets, evaluations, optimization
`mutagent traces`	Trace viewing, analysis, and export
`mutagent integrate`	Generate framework-specific SDK integration code
`mutagent playground`	Execute and test prompts with streaming support
`mutagent agents`	Agent CRUD (list, get, create, update, delete)
`mutagent workspaces`	View workspace details
`mutagent providers`	View and test LLM providers
`mutagent explore`	Scan codebase for prompts, datasets, and markers
`mutagent skills`	Install MutagenT CLI skill for coding agents
`mutagent hooks`	Hook handlers for AI coding assistant telemetry (Claude Code)
`mutagent usage`	Show resource counts and plan limits

Prompt Subcommands

The prompts command contains nested command groups for the full evaluate-optimize workflow:

Subcommand	Description
`prompts list / get / create / update / delete`	Prompt CRUD
`prompts create --output-schema`	Structured output schema (required for optimization)
`prompts dataset list / add / delete`	Dataset management (inline `-d` JSON)
`prompts evaluation list / get / create / delete`	Evaluation criteria management
`prompts evaluation create --guided`	Interactive criteria builder
`prompts optimize start / status / results`	Optimization with `--max-iterations`, `--target-score`, `--model`

Global Options

Option	Description
`--json`	Output results as JSON (for AI agents and automation)
`--non-interactive`	Disable 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
`--help`	Show help for any command (includes examples and workflow hints)
`-v, --version`	Show CLI version

Quick Start

bun add -g @mutagent/cli

npm install -g @mutagent/cli

# Download the standalone binary - no Bun or Node required
# See Installation guide for platform-specific URLs
curl -fsSL https://github.com/mutagent/cli/releases/latest/download/mutagent-$(uname -s)-$(uname -m) -o mutagent
chmod +x mutagent && sudo mv mutagent /usr/local/bin/

# 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:

Artifact	Purpose
`.mutagent/mutation-context.md`	Local context file tracking discovered prompts, uploaded resources, and optimization history
`MutagenT:START` / `MutagenT:END` markers	Comment markers in source files identifying managed prompts
`mutagent auth status`	Shows 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

Getting Started

CLI

Integrations

Tracing

SDK

CLI Overview

MutagenT CLI

Why CLI First?

AI Agent Integration

Progressive Disclosure

JSON Output

CI/CD Ready

Architecture

Command Structure

Top-Level Commands

Prompt Subcommands

Global Options

Quick Start

Post-Onboarding Flow

Evaluate-Optimize Workflow

For AI Agents

State Tracking

Key Behaviors

What’s Next

Installation

Commands

Integrations

​MutagenT CLI

​Why CLI First?

AI Agent Integration

Progressive Disclosure

JSON Output

CI/CD Ready

​Architecture

​Command Structure

​Top-Level Commands

​Prompt Subcommands

​Global Options

​Quick Start

​Post-Onboarding Flow

​Evaluate-Optimize Workflow

​For AI Agents

​State Tracking

​Key Behaviors

​What’s Next

Installation

Commands

Integrations

MutagenT CLI

Why CLI First?

Architecture

Command Structure

Top-Level Commands

Prompt Subcommands

Global Options

Quick Start

Post-Onboarding Flow

Evaluate-Optimize Workflow

For AI Agents

State Tracking

Key Behaviors

What’s Next