> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> MutagenT Command Line Interface - AI-native, CLI-first developer experience

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

<Tip>
  **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.
</Tip>

## Why CLI First?

<CardGroup cols={2}>
  <Card title="AI Agent Integration" icon="robot">
    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.
  </Card>

  <Card title="Progressive Disclosure" icon="layer-group">
    Every command and subcommand supports `--help` with examples. AI agents can discover capabilities incrementally without reading docs.
  </Card>

  <Card title="JSON Output" icon="code">
    All commands support `--json` for machine-readable output. JSON responses include `_links` with deep links to app.mutagent.io for easy navigation.
  </Card>

  <Card title="CI/CD Ready" icon="gears">
    `--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.
  </Card>
</CardGroup>

## Architecture

<Mermaid>
  flowchart LR
  CLI\["mutagent CLI"]
  SDK\["@mutagent/sdk"]
  API\["MutagenT API"]
  UI\["app.mutagent.io"]

  CLI -->|"TypeScript SDK"| SDK
  SDK -->|"REST + SSE"| API
  CLI -.->|"\_links in --json"| UI
</Mermaid>

## Command Structure

```bash theme={null}
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

<CodeGroup>
  ```bash bun (recommended) theme={null}
  bun add -g @mutagent/cli
  ```

  ```bash npm theme={null}
  npm install -g @mutagent/cli
  ```

  ```bash Binary (standalone) theme={null}
  # 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/
  ```
</CodeGroup>

```bash theme={null}
# 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:

<Mermaid>
  flowchart TD
  LOGIN\["mutagent auth login"] --> MENU\["Post-Onboarding Menu"]
  MENU -->|"Path A"| INTEGRATE\["Guided Integration"]
  MENU -->|"Path B"| OPTIMIZE\["Quick Optimization"]
  MENU -->|"Path C"| EXIT\["Exit - Manual Mode"]

  INTEGRATE --> EXPLORE\_A\["mutagent explore"]
  EXPLORE\_A --> FRAMEWORK\["Select Framework"]
  FRAMEWORK --> INTEGRATE\_CMD\["mutagent integrate \<framework>"]
  INTEGRATE\_CMD --> VERIFY\["mutagent integrate --verify"]

  OPTIMIZE --> EXPLORE\_B\["mutagent explore"]
  EXPLORE\_B --> CREATE\["mutagent prompts create"]
  CREATE --> EVAL\["mutagent prompts evaluation create"]
  EVAL --> DATASET\["mutagent prompts dataset add"]
  DATASET --> OPT\["mutagent prompts optimize start"]
  OPT --> SCORECARD\["Review Scorecard → Apply/Reject"]
</Mermaid>

**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.

<Tip>
  You can always re-enter the guided flows later. Run `mutagent explore` to scan your codebase, or jump directly into any command.
</Tip>

## Evaluate-Optimize Workflow

The CLI includes built-in workflow guidance in its `--help` output. The core loop is:

```bash theme={null}
# 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>
```

<Note>
  **Provider setup required**: Optimization requires at least one LLM provider to be configured. Set up providers at [app.mutagent.io/settings/providers](https://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.
</Note>

## For AI Agents

When working with AI coding assistants like Claude Code:

```bash theme={null}
# 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
```

<Note>
  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.
</Note>

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

```bash theme={null}
# 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

<CardGroup cols={3}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install and configure the CLI
  </Card>

  <Card title="Commands" icon="terminal" href="/cli/commands">
    Full command reference
  </Card>

  <Card title="Integrations" icon="plug" href="/cli/integrations">
    Generate framework integration code
  </Card>
</CardGroup>