# MutagenT CLI

```
  ███╗   ███╗██╗   ██╗████████╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗
  ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
  ██╔████╔██║██║   ██║   ██║   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║
  ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║
  ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║
  ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝
                          ██████╗██╗     ██╗
                         ██╔════╝██║     ██║
                         ██║     ██║     ██║
                         ██║     ██║     ██║
                         ╚██████╗███████╗██║
                          ╚═════╝╚══════╝╚═╝
```

<p align="center">
  <a href="https://www.npmjs.com/package/@mutagent/cli"><img src="https://img.shields.io/npm/v/@mutagent/cli?style=for-the-badge&color=cb3837&logo=npm&logoColor=white" alt="npm"></a>
  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.0+-f472b6?style=for-the-badge&logo=bun&logoColor=white" alt="Bun"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22+-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"></a>
  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"></a>
  <a href="#"><img src="https://img.shields.io/badge/License-Proprietary-ff6b6b?style=for-the-badge" alt="License: Proprietary"></a>
</p>

<p align="center">
  <strong>Optimize Prompts. Manage Agents. Integrate Any Framework.</strong>
</p>

---

## What is MutagenT CLI?

MutagenT CLI is the command-line interface for the **MutagenT AI platform** — a next-generation prompt optimization and observability system designed for AI-native development workflows.

### Key Features

- **Prompt-Centric**: Datasets, evaluations, and optimizations are all scoped to prompts
- **Native Tracing**: Built-in trace observability without external dependencies
- **AI-First Design**: Every command supports `--json` with `_links` for programmatic usage
- **Framework Integrations**: One-command setup for Mastra, LangChain, LangGraph, Vercel AI SDK, Claude Code
- **Bun-Native**: Built for speed with Bun runtime (Node.js 18+ compatible)
- **Post-Onboarding Flow**: Guided paths after login for integration or optimization
- **Codebase Exploration**: `mutagent explore` scans your code for prompts, datasets, and markers
- **Optimization Scorecard**: Before/after comparison with apply/reject flow
- **State Tracking**: `.mutagent/mutation-context.md` tracks your entire workflow locally

---

## Interaction Flow Map

This is the complete map of all user-facing routes through the CLI. Use this as a reference for UX decisions.

```mermaid
flowchart TD
    INSTALL["npm i -g @mutagent/cli"] --> AUTH_CHOICE{How to authenticate?}

    AUTH_CHOICE -->|Interactive| AUTH_LOGIN["mutagent auth login"]
    AUTH_CHOICE -->|Browser OAuth| AUTH_BROWSER["mutagent auth login --browser"]
    AUTH_CHOICE -->|API Key| AUTH_KEY["mutagent auth login --api-key mg_..."]
    AUTH_CHOICE -->|Env Var| AUTH_ENV["export MUTAGENT_API_KEY=mg_..."]

    AUTH_LOGIN --> ONBOARD
    AUTH_BROWSER --> ONBOARD
    AUTH_KEY --> ONBOARD
    AUTH_ENV --> MANUAL

    subgraph ONBOARD ["Post-Onboarding Menu (interactive only)"]
        direction TB
        MENU["What would you like to do?"]
        PATH_A["A: Guided Integration"]
        PATH_B["B: Quick Optimization"]
        PATH_C["C: Exit — manual mode"]
        MENU --> PATH_A
        MENU --> PATH_B
        MENU --> PATH_C
    end

    PATH_C --> MANUAL
    PATH_A --> EXPLORE_A["mutagent explore (auto-scan)"]
    PATH_B --> EXPLORE_B["mutagent explore (auto-scan)"]

    EXPLORE_A --> FW_SELECT["Select framework"]
    FW_SELECT --> INTEGRATE["mutagent integrate <framework>"]
    INTEGRATE --> VERIFY["mutagent integrate <fw> --verify"]
    VERIFY --> MANUAL

    EXPLORE_B --> PROMPT_CREATE
    PROMPT_CREATE --> EVAL_CREATE
    EVAL_CREATE --> DS_ADD
    DS_ADD --> OPT_START
    OPT_START --> OPT_STATUS
    OPT_STATUS --> OPT_RESULTS
    OPT_RESULTS --> SCORECARD["Scorecard: Apply / Reject"]
    SCORECARD -->|Apply| PROMPT_UPDATED["Prompt updated (platform + local)"]
    SCORECARD -->|Reject| MANUAL

    subgraph MANUAL ["Manual CLI Usage"]
        direction TB

        subgraph AUTH_CMDS ["Auth & Config"]
            AUTH_STATUS["mutagent auth status"]
            AUTH_LOGOUT["mutagent auth logout"]
            CONFIG_LIST["mutagent config list"]
            CONFIG_GET["mutagent config get <key>"]
            CONFIG_SET_WS["mutagent config set workspace <id>"]
            CONFIG_SET_ORG["mutagent config set org <id>"]
        end

        subgraph DISCOVER ["Discovery"]
            EXPLORE["mutagent explore"]
            EXPLORE_PATH["mutagent explore --path ./src"]
            EXPLORE_MARKERS["mutagent explore --markers-only"]
            SKILLS["mutagent skills install"]
        end

        subgraph PROMPT_CMDS ["Prompt CRUD"]
            PROMPT_LIST["mutagent prompts list"]
            PROMPT_GET["mutagent prompts get <id>"]
            PROMPT_CREATE["mutagent prompts create"]
            PROMPT_UPDATE["mutagent prompts update <id>"]
            PROMPT_DELETE["mutagent prompts delete <id>"]
        end

        subgraph DATASET_CMDS ["Dataset Management"]
            DS_LIST["mutagent prompts dataset list <pid>"]
            DS_ADD["mutagent prompts dataset add <pid>"]
            DS_DELETE["mutagent prompts dataset delete <pid> <did>"]
        end

        subgraph EVAL_CMDS ["Evaluations"]
            EVAL_LIST["mutagent prompts evaluation list <pid>"]
            EVAL_CREATE["mutagent prompts evaluation create <pid>"]
            EVAL_GUIDED["mutagent prompts evaluation create <pid> --guided"]
            EVAL_RESULTS["mutagent prompts evaluation results <rid>"]
        end

        subgraph OPT_CMDS ["Optimization"]
            OPT_START["mutagent prompts optimize start <pid>"]
            OPT_STATUS["mutagent prompts optimize status <jid>"]
            OPT_RESULTS["mutagent prompts optimize results <jid>"]
        end

        subgraph TRACE_CMDS ["Traces"]
            TRACE_LIST["mutagent traces list"]
            TRACE_GET["mutagent traces get <id>"]
            TRACE_ANALYZE["mutagent traces analyze <pid>"]
            TRACE_EXPORT["mutagent traces export"]
        end

        subgraph INTEGRATION_CMDS ["Integrations"]
            INT_LIST["mutagent integrate list"]
            INT_FW["mutagent integrate <framework>"]
            INT_VERIFY["mutagent integrate <fw> --verify"]
        end

        subgraph PLAYGROUND_CMDS ["Playground"]
            PG_RUN["mutagent playground run <pid>"]
            PG_STREAM["mutagent playground run <pid> --stream"]
        end

        subgraph PLATFORM_CMDS ["Platform (read-only)"]
            WS_LIST["mutagent workspaces list"]
            WS_GET["mutagent workspaces get <id>"]
            PROV_LIST["mutagent providers list"]
            PROV_GET["mutagent providers get <id>"]
            PROV_TEST["mutagent providers test <id>"]
            AGENTS_LIST["mutagent agents list"]
            AGENTS_GET["mutagent agents get <id>"]
        end
    end
```

### Evaluate-Optimize Loop (Detail)

```mermaid
flowchart LR
    CREATE["prompts create\n-d / --file / --raw"] --> DATASET["dataset add\n--file / -d"]
    DATASET --> EVAL["evaluation create\n--guided / --file / -d"]
    EVAL --> OPT["optimize start\n--dataset --max-iterations"]
    OPT --> STATUS["optimize status"]
    STATUS -->|poll| STATUS
    STATUS --> RESULTS["optimize results\n(scorecard)"]
    RESULTS -->|Apply| UPDATE["prompts update\n(new version)"]
    RESULTS -->|Reject| TWEAK["Adjust prompt/eval\nand re-run"]
    TWEAK --> OPT
```

### State Tracking Flow

```mermaid
flowchart LR
    EXPLORE["mutagent explore"] -->|writes| CTX[".mutagent/mutation-context.md"]
    CREATE["prompts create"] -->|updates| CTX
    UPLOAD["dataset add"] -->|updates| CTX
    EVAL["evaluation create"] -->|updates| CTX
    OPTIMIZE["optimize results --apply"] -->|updates| CTX
    MARKERS["MutagenT:START/END\ncomment markers"] -->|tracked by| CTX
    STATUS["auth status"] -->|reads| CTX
```

---

## Installation

### Using Bun (Recommended)

```bash
bun install -g @mutagent/cli
```

### Using npm

```bash
npm install -g @mutagent/cli
```

### Standalone Binary

```bash
# No Bun or Node.js required
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/
```

### Verify Installation

```bash
mutagent --version
```

---

## Quick Start

### 1. Authenticate

```bash
# End users — browser OAuth (handles signup, onboarding, CLI authorization)
mutagent login

# Force browser flow (skip method prompt)
mutagent login --browser

# CI / AI agent — set env var then run (no prompts, no browser)
export MUTAGENT_API_KEY="mt_live_xxxx"
mutagent login --json

# Back-compat alias — behaves identically to `mutagent login`
mutagent auth login
```

> `mutagent login` is the canonical command. `mutagent auth login` is preserved
> as a back-compat alias; both behave identically.

### 2. Post-Onboarding (Interactive)

After login, the CLI offers 3 paths:

| Path | Description |
|------|-------------|
| **A: Guided Integration** | Auto-scans codebase, selects framework, generates integration code |
| **B: Quick Optimization** | Auto-scans codebase, uploads prompt, creates eval, runs optimization |
| **C: Exit** | Skip guidance, use CLI manually |

### 3. Explore Your Codebase

```bash
mutagent explore                    # Scan current directory
mutagent explore --path ./src       # Scan specific path
mutagent explore --markers-only     # Find existing MutagenT markers only
```

### 4. Create & Optimize

```bash
# Create a prompt (inline JSON — recommended for AI agents)
mutagent prompts create -d '{"name":"summarizer","systemPrompt":"Summarize the text","humanPrompt":"{{text}}","outputSchema":{"type":"object","properties":{"summary":{"type":"string"}}}}'

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

# Create evaluation criteria (guided interactive mode)
mutagent prompts evaluation create <prompt-id> --guided

# Start optimization
mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --max-iterations 1

# Review results (shows scorecard with apply/reject)
mutagent prompts optimize results <job-id>
```

### 5. Get Framework Integration

```bash
mutagent integrate mastra       # Mastra
mutagent integrate langchain    # LangChain
mutagent integrate langgraph    # LangGraph
mutagent integrate vercel-ai    # Vercel AI SDK
mutagent integrate openai       # OpenAI SDK
mutagent integrate claude-code  # Claude Code
```

---

## Commands Reference

### Global Options

| Option | Description |
|--------|-------------|
| `--json` | Output results as JSON with `_links` to web UI |
| `--non-interactive` | Disable all interactive prompts (also: `CI=true`) |
| `--api-key <key>` | Override API key for this command |
| `--endpoint <url>` | Override API endpoint |
| `--help` | Show help with examples and workflow hints |
| `-v, --version` | Show CLI version |

### Environment Variables

| Variable | Description |
|----------|-------------|
| `MUTAGENT_API_KEY` | API key (skips login entirely) |
| `MUTAGENT_ENDPOINT` | Custom API endpoint |
| `MUTAGENT_NON_INTERACTIVE=true` | Non-interactive mode |
| `CI=true` | Enables non-interactive mode |

### Authentication & Configuration

```bash
mutagent auth login                 # Interactive login
mutagent auth login --browser       # Browser OAuth
mutagent auth login --api-key KEY   # API key login
mutagent auth status                # Check auth + onboarding state + resource counts
mutagent auth logout                # Clear credentials

mutagent config list                # List all config values
mutagent config get <key>           # Get specific value
mutagent config set workspace <id>  # Set default workspace
mutagent config set org <id>        # Set default organization
```

### Discovery & Skills

```bash
# Explore codebase for prompts, datasets, MutagenT markers
mutagent explore                          # Scan current directory
mutagent explore --path ./src             # Scan specific path
mutagent explore --include "**/*.py"      # Python projects only
mutagent explore --markers-only           # Only find MutagenT:START/END markers
mutagent explore --json                   # JSON output

# Install Claude Code skill
mutagent skills install                   # Creates .claude/skills/mutagent-cli/SKILL.md
```

### Prompts

```bash
# List / Get
mutagent prompts list
mutagent prompts get <id>
mutagent prompts get <id> --with-datasets --with-evals

# Create (multiple input methods, priority order)
mutagent prompts create -d '{"name":"...","systemPrompt":"...","outputSchema":{...}}'   # Inline JSON (recommended)
mutagent prompts create --file prompt.json                                               # From JSON file
mutagent prompts create --name "my-prompt" --raw-file prompt.txt                         # From text file
mutagent prompts create --name "my-prompt" --system "You are..." --human "{{input}}"     # System + human
mutagent prompts create --name "my-prompt" --raw "Summarize: {{text}}"                   # Raw text
mutagent prompts create --name "chat" --messages '[{"role":"system","content":"..."}]'   # Messages array

# Update (same input methods as create)
mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated"}'
mutagent prompts update <id> --name "new-name"
mutagent prompts update <id> --file updated.json

# Delete
mutagent prompts delete <id>
mutagent prompts delete <id> --force
```

> **outputSchema** is required for optimization. Include it in `--data`, `--file`, or use `--output-schema`. In interactive mode, you will be prompted if missing.

### Datasets

```bash
mutagent prompts dataset list <prompt-id>

# Add from file (JSON, JSONL, CSV)
mutagent prompts dataset add <prompt-id> --file data.json --name "My Dataset"

# Add inline JSON
mutagent prompts dataset add <prompt-id> -d '[{"input":{...},"expectedOutput":{...}}]' --name "Inline Data"

mutagent prompts dataset delete <prompt-id> <dataset-id>
```

### Evaluations

```bash
mutagent prompts evaluation list <prompt-id>

# Guided interactive mode (fetches outputSchema, helps build criteria)
mutagent prompts evaluation create <prompt-id> --guided

# Inline JSON
mutagent prompts evaluation create <prompt-id> -d '{"name":"Accuracy","evalConfig":{"criteria":[...]}}'

# From file with dataset association
mutagent prompts evaluation create <prompt-id> --name "Quality" --file criteria.json --dataset <dataset-id>

mutagent prompts evaluation results <run-id>
```

> `-d` is `--data` (inline JSON). `--dataset` requires the full flag name (no shorthand).

### Optimization

```bash
mutagent prompts optimize start <prompt-id> --dataset <dataset-id>
mutagent prompts optimize start <prompt-id> --dataset <id> --max-iterations 5 --target-score 0.95

mutagent prompts optimize status <job-id>

# Results include scorecard with before/after comparison and apply/reject flow
mutagent prompts optimize results <job-id>
```

### Traces

```bash
mutagent traces list
mutagent traces list --prompt <prompt-id> --limit 10
mutagent traces get <trace-id>
mutagent traces analyze <prompt-id>
mutagent traces export --format json --output traces.json
mutagent traces export --format csv --prompt <prompt-id>
```

### Framework Integration

```bash
mutagent integrate                    # Auto-detect framework
mutagent integrate list               # List supported frameworks
mutagent integrate <framework>        # Generate integration code
mutagent integrate <fw> --verify      # Verify integration setup
mutagent integrate <fw> --output FILE # Save to file
mutagent integrate <fw> --raw         # Raw markdown output
```

| Framework | Package | Description |
|-----------|---------|-------------|
| `mastra` | `@mastra/core` | Modern AI agent framework |
| `langchain` | `langchain` | Popular LLM framework |
| `langgraph` | `@langchain/langgraph` | Agent workflow framework |
| `vercel-ai` | `ai` | AI SDK for streaming chat |
| `openai` | `openai` | Direct OpenAI SDK integration |
| `claude-code` | MCP Server | Native Anthropic integration |
| `generic` | `openai` | Any OpenAI-compatible API |

### Playground

```bash
mutagent playground run <prompt-id> --input '{"topic": "AI"}'
mutagent playground run <prompt-id> --input '{"topic": "AI"}' --stream
mutagent playground run <prompt-id> --system "You are..." --human "Hello!"
mutagent playground run <prompt-id> --messages '[{"role":"user","content":"Hi"}]'
mutagent playground run <prompt-id> --input '{}' --model gpt-4o
```

### Platform (Read-Only)

```bash
# Workspaces
mutagent workspaces list
mutagent workspaces get <id>

# Providers
mutagent providers list
mutagent providers get <id>
mutagent providers test <id>

# Agents
mutagent agents list
mutagent agents get <id>
mutagent agents create --name "Agent" --slug agent --system-prompt "..."
mutagent agents update <id> --status paused
mutagent agents delete <id>
```

---

## AI-First Usage

Every command supports `--json` for machine-readable output with `_links` to the web dashboard:

```bash
# Zero-config with env var
export MUTAGENT_API_KEY="mg_live_xxxx"

# Discover commands
mutagent --help

# JSON output with deep links
mutagent prompts list --json
mutagent prompts get <id> --json

# Inline JSON for create/update (recommended for AI agents)
mutagent prompts create -d '{"name":"my-prompt","systemPrompt":"...","outputSchema":{...}}'

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

# Generate integration code (raw markdown)
mutagent integrate langchain --raw

# Install skill for Claude Code
mutagent skills install
```

### JSON Output Format

```json
{
  "data": { "id": 42, "name": "my-prompt", "..." : "..." },
  "_links": {
    "dashboard": "https://app.mutagent.io/prompts/dashboard?prompt=42",
    "api": "/api/prompts/42",
    "datasets": "https://app.mutagent.io/prompts/dashboard?prompt=42&tab=datasets",
    "evaluations": "https://app.mutagent.io/prompts/dashboard?prompt=42&tab=evaluations"
  }
}
```

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Authentication required |
| `3` | Configuration error |
| `5` | Network error |
| `6` | Rate limit exceeded |
| `8` | Permission error |

---

## State Tracking

The CLI maintains local state to track your MutagenT workflow:

| Artifact | Location | Purpose |
|----------|----------|---------|
| **Mutation context** | `.mutagent/mutation-context.md` | Tracks discovered prompts, uploaded resources, optimization history |
| **Comment markers** | Source files | `MutagenT:START` / `MutagenT:END` markers identifying managed prompts |
| **Auth status** | `mutagent auth status` | Shows onboarding state, context file status, resource counts |
| **Claude Code skill** | `.claude/skills/mutagent-cli/SKILL.md` | Teaches AI agents how to use MutagenT CLI |

```bash
# Scan codebase and populate context
mutagent explore

# Check your current state
mutagent auth status

# Install Claude Code skill
mutagent skills install
```

---

## Configuration

### Environment Variables

```bash
MUTAGENT_API_KEY=mg_live_xxxxxxxx
MUTAGENT_ENDPOINT=https://api.mutagent.io
MUTAGENT_APP_URL=https://app.mutagent.io
```

### RC Files

Create `.mutagentrc.json`:

```json
{
  "endpoint": "https://api.mutagent.io",
  "format": "table"
}
```

### Persistent Defaults

```bash
mutagent config set workspace <id>  # Avoid passing workspace on every command
mutagent config set org <id>        # Required for org-scoped API keys
```

### Global Config

Stored in `~/.config/mutagent/credentials.json` (created by `mutagent auth login`).

---

## Migration from Langfuse

```typescript
// Before (Langfuse)
import { Langfuse } from 'langfuse';
const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
});

// After (MutagenT)
import { initTracing } from '@mutagent/sdk/tracing';
initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

// Framework-specific: use integration packages
import { MutagentCallbackHandler } from '@mutagent/langchain';
const handler = new MutagentCallbackHandler();
```

---

## Development

### Prerequisites

- [Bun](https://bun.sh) >= 1.0.0
- Node.js >= 18.0.0 (fallback)

### Setup

```bash
git clone https://github.com/mutagent/mutagent-cli.git
cd mutagent-cli
bun install
```

### Commands

```bash
bun run dev          # Run in development mode
bun run build        # Build
bun run typecheck    # Type check
bun run lint         # Lint
bun run lint:fix     # Lint with auto-fix
bun run test         # Run all tests (574+ tests)
bun run verify       # Full verification (lint + typecheck + build + test)
```

---

## See Also

- **[@mutagent/sdk](https://www.npmjs.com/package/@mutagent/sdk)** — TypeScript SDK for programmatic access
- **[docs.mutagent.io](https://docs.mutagent.io)** — Full platform documentation
- **[CLI Commands Reference](https://docs.mutagent.io/cli/commands)** — All commands with flags
- **[Integration Guides](https://docs.mutagent.io/integrations/overview)** — Mastra, LangChain, LangGraph, Vercel AI
- **[Tracing Setup](https://docs.mutagent.io/tracing/setup)** — OTel integration walkthrough
- **[mutagent.io](https://mutagent.io)** — Homepage

---

## License

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

(c) 2026 MutagenT. All rights reserved.

---

<p align="center">
  <sub>Built with care by the MutagenT Team</sub>
</p>

<p align="center">
  <a href="https://twitter.com/mutagent">Twitter</a> •
  <a href="https://discord.gg/mutagent">Discord</a> •
  <a href="https://mutagent.io">Website</a>
</p>