@mutagent/cli 0.1.13 → 0.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +461 -222
  2. package/dist/bin/cli.js +2004 -492
  3. package/dist/bin/cli.js.map +20 -13
  4. package/dist/index.js +124 -90
  5. package/dist/index.js.map +7 -7
  6. package/package.json +3 -8
package/README.md CHANGED
@@ -36,21 +36,179 @@
36
36
 
37
37
  ---
38
38
 
39
- ## 🚀 What is MutagenT CLI?
39
+ ## What is MutagenT CLI?
40
40
 
41
41
  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.
42
42
 
43
43
  ### Key Features
44
44
 
45
- - 🎯 **Prompt-Centric**: Datasets, evaluations, and optimizations are all scoped to prompts
46
- - 📊 **Langfuse Replacement**: Native trace observability without external dependencies
47
- - 🤖 **AI-First Design**: Every command supports `--json` for programmatic usage
48
- - 🔌 **Framework Integrations**: One-command setup for Mastra, LangChain, LangGraph, Vercel AI SDK, Claude Code
49
- - ⚡ **Bun-Native**: Built for speed with Bun runtime (Node.js 18+ compatible)
45
+ - **Prompt-Centric**: Datasets, evaluations, and optimizations are all scoped to prompts
46
+ - **Langfuse Replacement**: Native trace observability without external dependencies
47
+ - **AI-First Design**: Every command supports `--json` with `_links` for programmatic usage
48
+ - **Framework Integrations**: One-command setup for Mastra, LangChain, LangGraph, Vercel AI SDK, Claude Code
49
+ - **Bun-Native**: Built for speed with Bun runtime (Node.js 18+ compatible)
50
+ - **Post-Onboarding Flow**: Guided paths after login for integration or optimization
51
+ - **Codebase Exploration**: `mutagent explore` scans your code for prompts, datasets, and markers
52
+ - **Optimization Scorecard**: Before/after comparison with apply/reject flow
53
+ - **State Tracking**: `.mutagent/mutation-context.md` tracks your entire workflow locally
50
54
 
51
55
  ---
52
56
 
53
- ## 📦 Installation
57
+ ## Interaction Flow Map
58
+
59
+ This is the complete map of all user-facing routes through the CLI. Use this as a reference for UX decisions.
60
+
61
+ ```mermaid
62
+ flowchart TD
63
+ INSTALL["npm i -g @mutagent/cli"] --> AUTH_CHOICE{How to authenticate?}
64
+
65
+ AUTH_CHOICE -->|Interactive| AUTH_LOGIN["mutagent auth login"]
66
+ AUTH_CHOICE -->|Browser OAuth| AUTH_BROWSER["mutagent auth login --browser"]
67
+ AUTH_CHOICE -->|API Key| AUTH_KEY["mutagent auth login --api-key mg_..."]
68
+ AUTH_CHOICE -->|Env Var| AUTH_ENV["export MUTAGENT_API_KEY=mg_..."]
69
+
70
+ AUTH_LOGIN --> ONBOARD
71
+ AUTH_BROWSER --> ONBOARD
72
+ AUTH_KEY --> ONBOARD
73
+ AUTH_ENV --> MANUAL
74
+
75
+ subgraph ONBOARD ["Post-Onboarding Menu (interactive only)"]
76
+ direction TB
77
+ MENU["What would you like to do?"]
78
+ PATH_A["A: Guided Integration"]
79
+ PATH_B["B: Quick Optimization"]
80
+ PATH_C["C: Exit — manual mode"]
81
+ MENU --> PATH_A
82
+ MENU --> PATH_B
83
+ MENU --> PATH_C
84
+ end
85
+
86
+ PATH_C --> MANUAL
87
+ PATH_A --> EXPLORE_A["mutagent explore (auto-scan)"]
88
+ PATH_B --> EXPLORE_B["mutagent explore (auto-scan)"]
89
+
90
+ EXPLORE_A --> FW_SELECT["Select framework"]
91
+ FW_SELECT --> INTEGRATE["mutagent integrate <framework>"]
92
+ INTEGRATE --> VERIFY["mutagent integrate <fw> --verify"]
93
+ VERIFY --> MANUAL
94
+
95
+ EXPLORE_B --> PROMPT_CREATE
96
+ PROMPT_CREATE --> EVAL_CREATE
97
+ EVAL_CREATE --> DS_ADD
98
+ DS_ADD --> OPT_START
99
+ OPT_START --> OPT_STATUS
100
+ OPT_STATUS --> OPT_RESULTS
101
+ OPT_RESULTS --> SCORECARD["Scorecard: Apply / Reject"]
102
+ SCORECARD -->|Apply| PROMPT_UPDATED["Prompt updated (platform + local)"]
103
+ SCORECARD -->|Reject| MANUAL
104
+
105
+ subgraph MANUAL ["Manual CLI Usage"]
106
+ direction TB
107
+
108
+ subgraph AUTH_CMDS ["Auth & Config"]
109
+ AUTH_STATUS["mutagent auth status"]
110
+ AUTH_LOGOUT["mutagent auth logout"]
111
+ CONFIG_LIST["mutagent config list"]
112
+ CONFIG_GET["mutagent config get <key>"]
113
+ CONFIG_SET_WS["mutagent config set workspace <id>"]
114
+ CONFIG_SET_ORG["mutagent config set org <id>"]
115
+ end
116
+
117
+ subgraph DISCOVER ["Discovery"]
118
+ EXPLORE["mutagent explore"]
119
+ EXPLORE_PATH["mutagent explore --path ./src"]
120
+ EXPLORE_MARKERS["mutagent explore --markers-only"]
121
+ SKILLS["mutagent skills install"]
122
+ end
123
+
124
+ subgraph PROMPT_CMDS ["Prompt CRUD"]
125
+ PROMPT_LIST["mutagent prompts list"]
126
+ PROMPT_GET["mutagent prompts get <id>"]
127
+ PROMPT_CREATE["mutagent prompts create"]
128
+ PROMPT_UPDATE["mutagent prompts update <id>"]
129
+ PROMPT_DELETE["mutagent prompts delete <id>"]
130
+ end
131
+
132
+ subgraph DATASET_CMDS ["Dataset Management"]
133
+ DS_LIST["mutagent prompts dataset list <pid>"]
134
+ DS_ADD["mutagent prompts dataset add <pid>"]
135
+ DS_REMOVE["mutagent prompts dataset remove <pid> <did>"]
136
+ end
137
+
138
+ subgraph EVAL_CMDS ["Evaluations"]
139
+ EVAL_LIST["mutagent prompts evaluation list <pid>"]
140
+ EVAL_CREATE["mutagent prompts evaluation create <pid>"]
141
+ EVAL_GUIDED["mutagent prompts evaluation create <pid> --guided"]
142
+ EVAL_RESULTS["mutagent prompts evaluation results <rid>"]
143
+ end
144
+
145
+ subgraph OPT_CMDS ["Optimization"]
146
+ OPT_START["mutagent prompts optimize start <pid>"]
147
+ OPT_STATUS["mutagent prompts optimize status <jid>"]
148
+ OPT_RESULTS["mutagent prompts optimize results <jid>"]
149
+ end
150
+
151
+ subgraph TRACE_CMDS ["Traces"]
152
+ TRACE_LIST["mutagent traces list"]
153
+ TRACE_GET["mutagent traces get <id>"]
154
+ TRACE_ANALYZE["mutagent traces analyze <pid>"]
155
+ TRACE_EXPORT["mutagent traces export"]
156
+ end
157
+
158
+ subgraph INTEGRATION_CMDS ["Integrations"]
159
+ INT_LIST["mutagent integrate list"]
160
+ INT_FW["mutagent integrate <framework>"]
161
+ INT_VERIFY["mutagent integrate <fw> --verify"]
162
+ end
163
+
164
+ subgraph PLAYGROUND_CMDS ["Playground"]
165
+ PG_RUN["mutagent playground run <pid>"]
166
+ PG_STREAM["mutagent playground run <pid> --stream"]
167
+ end
168
+
169
+ subgraph PLATFORM_CMDS ["Platform (read-only)"]
170
+ WS_LIST["mutagent workspaces list"]
171
+ WS_GET["mutagent workspaces get <id>"]
172
+ PROV_LIST["mutagent providers list"]
173
+ PROV_GET["mutagent providers get <id>"]
174
+ PROV_TEST["mutagent providers test <id>"]
175
+ AGENTS_LIST["mutagent agents list"]
176
+ AGENTS_GET["mutagent agents get <id>"]
177
+ end
178
+ end
179
+ ```
180
+
181
+ ### Evaluate-Optimize Loop (Detail)
182
+
183
+ ```mermaid
184
+ flowchart LR
185
+ CREATE["prompts create\n-d / --file / --raw"] --> DATASET["dataset add\n--file / -d"]
186
+ DATASET --> EVAL["evaluation create\n--guided / --file / -d"]
187
+ EVAL --> OPT["optimize start\n--dataset --max-iterations"]
188
+ OPT --> STATUS["optimize status"]
189
+ STATUS -->|poll| STATUS
190
+ STATUS --> RESULTS["optimize results\n(scorecard)"]
191
+ RESULTS -->|Apply| UPDATE["prompts update\n(new version)"]
192
+ RESULTS -->|Reject| TWEAK["Adjust prompt/eval\nand re-run"]
193
+ TWEAK --> OPT
194
+ ```
195
+
196
+ ### State Tracking Flow
197
+
198
+ ```mermaid
199
+ flowchart LR
200
+ EXPLORE["mutagent explore"] -->|writes| CTX[".mutagent/mutation-context.md"]
201
+ CREATE["prompts create"] -->|updates| CTX
202
+ UPLOAD["dataset add"] -->|updates| CTX
203
+ EVAL["evaluation create"] -->|updates| CTX
204
+ OPTIMIZE["optimize results --apply"] -->|updates| CTX
205
+ MARKERS["MutagenT:START/END\ncomment markers"] -->|tracked by| CTX
206
+ STATUS["auth status"] -->|reads| CTX
207
+ ```
208
+
209
+ ---
210
+
211
+ ## Installation
54
212
 
55
213
  ### Using Bun (Recommended)
56
214
 
@@ -64,10 +222,12 @@ bun install -g @mutagent/cli
64
222
  npm install -g @mutagent/cli
65
223
  ```
66
224
 
67
- ### Using pnpm
225
+ ### Standalone Binary
68
226
 
69
227
  ```bash
70
- pnpm add -g @mutagent/cli
228
+ # No Bun or Node.js required
229
+ curl -fsSL https://github.com/mutagent/cli/releases/latest/download/mutagent-$(uname -s)-$(uname -m) -o mutagent
230
+ chmod +x mutagent && sudo mv mutagent /usr/local/bin/
71
231
  ```
72
232
 
73
233
  ### Verify Installation
@@ -78,288 +238,399 @@ mutagent --version
78
238
 
79
239
  ---
80
240
 
81
- ## 🔑 Quick Start
241
+ ## Quick Start
82
242
 
83
243
  ### 1. Authenticate
84
244
 
85
245
  ```bash
246
+ # Interactive (choose browser OAuth or API key)
86
247
  mutagent auth login
87
- # Enter your API key when prompted
88
- ```
89
248
 
90
- Or use environment variables:
249
+ # Browser OAuth directly
250
+ mutagent auth login --browser
91
251
 
92
- ```bash
93
- export MUTAGENT_API_KEY="sk_live_xxxxxxxx"
94
- export MUTAGENT_ENDPOINT="https://api.mutagent.io/v1"
252
+ # Non-interactive with API key (CI/CD)
253
+ mutagent auth login --api-key mg_live_xxxx
254
+
255
+ # Or just set the env var (skips login entirely)
256
+ export MUTAGENT_API_KEY="mg_live_xxxx"
95
257
  ```
96
258
 
97
- ### 2. Check Status
259
+ ### 2. Post-Onboarding (Interactive)
260
+
261
+ After login, the CLI offers 3 paths:
262
+
263
+ | Path | Description |
264
+ |------|-------------|
265
+ | **A: Guided Integration** | Auto-scans codebase, selects framework, generates integration code |
266
+ | **B: Quick Optimization** | Auto-scans codebase, uploads prompt, creates eval, runs optimization |
267
+ | **C: Exit** | Skip guidance, use CLI manually |
268
+
269
+ ### 3. Explore Your Codebase
98
270
 
99
271
  ```bash
100
- mutagent auth status
272
+ mutagent explore # Scan current directory
273
+ mutagent explore --path ./src # Scan specific path
274
+ mutagent explore --markers-only # Find existing MutagenT markers only
101
275
  ```
102
276
 
103
- ### 3. Get Framework Integration
277
+ ### 4. Create & Optimize
104
278
 
105
279
  ```bash
106
- # Interactive selection
107
- mutagent integrate
280
+ # Create a prompt (inline JSON — recommended for AI agents)
281
+ mutagent prompts create -d '{"name":"summarizer","systemPrompt":"Summarize the text","humanPrompt":"{{text}}","outputSchema":{"type":"object","properties":{"summary":{"type":"string"}}}}'
108
282
 
109
- # Direct framework
110
- mutagent integrate mastra
111
- mutagent integrate langchain
112
- mutagent integrate vercel-ai
113
- ```
283
+ # Upload a dataset
284
+ mutagent prompts dataset add <prompt-id> --file data.json --name "Training Data"
114
285
 
115
- ### 4. Start Using
286
+ # Create evaluation criteria (guided interactive mode)
287
+ mutagent prompts evaluation create <prompt-id> --guided
116
288
 
117
- ```bash
118
- # List prompts
119
- mutagent prompts list
289
+ # Start optimization
290
+ mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --max-iterations 3
120
291
 
121
- # Create a prompt
122
- mutagent prompts create --file ./my-prompt.json
292
+ # Review results (shows scorecard with apply/reject)
293
+ mutagent prompts optimize results <job-id>
294
+ ```
123
295
 
124
- # Run optimization
125
- mutagent prompts optimize <prompt-id> --dataset <dataset-id>
296
+ ### 5. Get Framework Integration
126
297
 
127
- # View traces (replaces Langfuse)
128
- mutagent traces list --prompt <prompt-id>
298
+ ```bash
299
+ mutagent integrate mastra # Mastra
300
+ mutagent integrate langchain # LangChain
301
+ mutagent integrate langgraph # LangGraph
302
+ mutagent integrate vercel-ai # Vercel AI SDK
303
+ mutagent integrate openai # OpenAI SDK
304
+ mutagent integrate claude-code # Claude Code
129
305
  ```
130
306
 
131
307
  ---
132
308
 
133
- ## 📚 Commands Reference
309
+ ## Commands Reference
134
310
 
135
311
  ### Global Options
136
312
 
137
313
  | Option | Description |
138
314
  |--------|-------------|
139
- | `--json` | Output results as JSON (for AI agents) |
140
- | `--api-key <key>` | MutagenT API key |
141
- | `--endpoint <url>` | MutagenT server endpoint |
142
- | `--help` | Display help for command |
143
- | `--version` | Display version number |
315
+ | `--json` | Output results as JSON with `_links` to web UI |
316
+ | `--non-interactive` | Disable all interactive prompts (also: `CI=true`) |
317
+ | `--api-key <key>` | Override API key for this command |
318
+ | `--endpoint <url>` | Override API endpoint |
319
+ | `--help` | Show help with examples and workflow hints |
320
+ | `-v, --version` | Show CLI version |
321
+
322
+ ### Environment Variables
323
+
324
+ | Variable | Description |
325
+ |----------|-------------|
326
+ | `MUTAGENT_API_KEY` | API key (skips login entirely) |
327
+ | `MUTAGENT_ENDPOINT` | Custom API endpoint |
328
+ | `MUTAGENT_NON_INTERACTIVE=true` | Non-interactive mode |
329
+ | `CI=true` | Enables non-interactive mode |
144
330
 
145
- ### Authentication
331
+ ### Authentication & Configuration
146
332
 
147
333
  ```bash
148
- mutagent auth login # Interactive login
149
- mutagent auth status # Check authentication
150
- mutagent auth logout # Clear credentials
334
+ mutagent auth login # Interactive login
335
+ mutagent auth login --browser # Browser OAuth
336
+ mutagent auth login --api-key KEY # API key login
337
+ mutagent auth status # Check auth + onboarding state + resource counts
338
+ mutagent auth logout # Clear credentials
339
+
340
+ mutagent config list # List all config values
341
+ mutagent config get <key> # Get specific value
342
+ mutagent config set workspace <id> # Set default workspace
343
+ mutagent config set org <id> # Set default organization
151
344
  ```
152
345
 
153
- ### Configuration
346
+ ### Discovery & Skills
154
347
 
155
348
  ```bash
156
- mutagent config list # List all configuration
157
- mutagent config get <key> # Get specific config value
349
+ # Explore codebase for prompts, datasets, MutagenT markers
350
+ mutagent explore # Scan current directory
351
+ mutagent explore --path ./src # Scan specific path
352
+ mutagent explore --include "**/*.py" # Python projects only
353
+ mutagent explore --markers-only # Only find MutagenT:START/END markers
354
+ mutagent explore --json # JSON output
355
+
356
+ # Install Claude Code skill
357
+ mutagent skills install # Creates .claude/skills/mutagent-cli/SKILL.md
158
358
  ```
159
359
 
160
360
  ### Prompts
161
361
 
162
- Prompts are the root entity. Datasets, evaluations, and optimizations are scoped to prompts.
163
-
164
362
  ```bash
165
- # CRUD Operations
166
- mutagent prompts list # List all prompts
167
- mutagent prompts get <id> # Get prompt details
168
- mutagent prompts get <id> --with-datasets # Include datasets
169
- mutagent prompts get <id> --with-evals # Include evaluations
170
- mutagent prompts create --file prompt.json # Create from file
171
- mutagent prompts create --name "My Prompt" --content "..."
172
- mutagent prompts update <id> --file prompt.json
363
+ # List / Get
364
+ mutagent prompts list
365
+ mutagent prompts get <id>
366
+ mutagent prompts get <id> --with-datasets --with-evals
367
+
368
+ # Create (multiple input methods, priority order)
369
+ mutagent prompts create -d '{"name":"...","systemPrompt":"...","outputSchema":{...}}' # Inline JSON (recommended)
370
+ mutagent prompts create --file prompt.json # From JSON file
371
+ mutagent prompts create --name "my-prompt" --raw-file prompt.txt # From text file
372
+ mutagent prompts create --name "my-prompt" --system "You are..." --human "{{input}}" # System + human
373
+ mutagent prompts create --name "my-prompt" --raw "Summarize: {{text}}" # Raw text
374
+ mutagent prompts create --name "chat" --messages '[{"role":"system","content":"..."}]' # Messages array
375
+
376
+ # Update (same input methods as create)
377
+ mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated"}'
378
+ mutagent prompts update <id> --name "new-name"
379
+ mutagent prompts update <id> --file updated.json
380
+
381
+ # Delete
173
382
  mutagent prompts delete <id>
383
+ mutagent prompts delete <id> --force
384
+ ```
174
385
 
175
- # Datasets (scoped to prompt)
176
- mutagent prompts datasets <prompt-id> # List datasets
177
- mutagent prompts datasets:add <id> --file data.jsonl # Add dataset
178
- mutagent prompts datasets:remove <id> <dataset-id> # Remove dataset
386
+ > **outputSchema** is required for optimization. Include it in `--data`, `--file`, or use `--output-schema`. In interactive mode, you will be prompted if missing.
179
387
 
180
- # Evaluations (scoped to prompt + dataset)
181
- mutagent prompts evals <prompt-id> # List evaluations
182
- mutagent prompts evals:run <id> --dataset <dataset-id> # Run evaluation
183
- mutagent prompts evals:results <run-id> # Get results
388
+ ### Datasets
184
389
 
185
- # Optimization (scoped to prompt + dataset)
186
- mutagent prompts optimize <id> --dataset <dataset-id> # Start optimization
187
- mutagent prompts optimize:status <job-id> # Check status
188
- mutagent prompts optimize:results <job-id> # Get results
189
- ```
390
+ ```bash
391
+ mutagent prompts dataset list <prompt-id>
190
392
 
191
- ### Traces (Langfuse Replacement)
393
+ # Add from file (JSON, JSONL, CSV)
394
+ mutagent prompts dataset add <prompt-id> --file data.json --name "My Dataset"
192
395
 
193
- ```bash
194
- mutagent traces list # List all traces
195
- mutagent traces list --prompt <id> # Filter by prompt
196
- mutagent traces get <trace-id> # Get trace details
197
- mutagent traces analyze <prompt-id> # Analyze trace patterns
198
- mutagent traces export --format json # Export as JSON
199
- mutagent traces export --format csv # Export as CSV
396
+ # Add inline JSON
397
+ mutagent prompts dataset add <prompt-id> -d '[{"input":{...},"expectedOutput":{...}}]' --name "Inline Data"
398
+
399
+ mutagent prompts dataset remove <prompt-id> <dataset-id>
200
400
  ```
201
401
 
202
- ### Framework Integration
402
+ ### Evaluations
203
403
 
204
404
  ```bash
205
- # List available frameworks
206
- mutagent integrate list
405
+ mutagent prompts evaluation list <prompt-id>
207
406
 
208
- # Get integration guide (markdown format)
209
- mutagent integrate mastra
210
- mutagent integrate langchain
211
- mutagent integrate langgraph
212
- mutagent integrate vercel-ai
213
- mutagent integrate claude-code
214
- mutagent integrate generic
407
+ # Guided interactive mode (fetches outputSchema, helps build criteria)
408
+ mutagent prompts evaluation create <prompt-id> --guided
215
409
 
216
- # Save to file
217
- mutagent integrate mastra --output ./INTEGRATION.md
410
+ # Inline JSON
411
+ mutagent prompts evaluation create <prompt-id> -d '{"name":"Accuracy","evalConfig":{"criteria":[...]}}'
218
412
 
219
- # Raw markdown output
220
- mutagent integrate mastra --raw
413
+ # From file with dataset association
414
+ mutagent prompts evaluation create <prompt-id> --name "Quality" --file criteria.json --dataset <dataset-id>
221
415
 
222
- # Verify integration
223
- mutagent integrate mastra --verify
416
+ mutagent prompts evaluation results <run-id>
224
417
  ```
225
418
 
226
- ---
227
-
228
- ## 🤖 AI-First Usage
419
+ > `-d` is `--data` (inline JSON). `--dataset` requires the full flag name (no shorthand).
229
420
 
230
- Every command supports `--json` for machine-readable output:
421
+ ### Optimization
231
422
 
232
423
  ```bash
233
- # AI agent checking available prompts
234
- mutagent --json prompts list
424
+ mutagent prompts optimize start <prompt-id> --dataset <dataset-id>
425
+ mutagent prompts optimize start <prompt-id> --dataset <id> --max-iterations 5 --target-score 0.95
426
+
427
+ mutagent prompts optimize status <job-id>
235
428
 
236
- # AI agent creating a prompt
237
- mutagent --json prompts create --file prompt.json
429
+ # Results include scorecard with before/after comparison and apply/reject flow
430
+ mutagent prompts optimize results <job-id>
431
+ ```
238
432
 
239
- # AI agent running evaluation
240
- mutagent --json prompts evals:run <id> --dataset <ds-id>
433
+ ### Traces
241
434
 
242
- # AI agent getting integration guide
243
- mutagent --json integrate mastra
435
+ ```bash
436
+ mutagent traces list
437
+ mutagent traces list --prompt <prompt-id> --limit 10
438
+ mutagent traces get <trace-id>
439
+ mutagent traces analyze <prompt-id>
440
+ mutagent traces export --format json --output traces.json
441
+ mutagent traces export --format csv --prompt <prompt-id>
244
442
  ```
245
443
 
246
- ### Exit Codes
444
+ ### Framework Integration
247
445
 
248
- | Code | Meaning |
249
- |------|---------|
250
- | `0` | Success |
251
- | `1` | Error |
252
- | `2` | Partial success / Authentication required |
446
+ ```bash
447
+ mutagent integrate # Auto-detect framework
448
+ mutagent integrate list # List supported frameworks
449
+ mutagent integrate <framework> # Generate integration code
450
+ mutagent integrate <fw> --verify # Verify integration setup
451
+ mutagent integrate <fw> --output FILE # Save to file
452
+ mutagent integrate <fw> --raw # Raw markdown output
453
+ ```
454
+
455
+ | Framework | Package | Description |
456
+ |-----------|---------|-------------|
457
+ | `mastra` | `@mastra/core` | Modern AI agent framework |
458
+ | `langchain` | `langchain` | Popular LLM framework |
459
+ | `langgraph` | `@langchain/langgraph` | Agent workflow framework |
460
+ | `vercel-ai` | `ai` | AI SDK for streaming chat |
461
+ | `openai` | `openai` | Direct OpenAI SDK integration |
462
+ | `claude-code` | MCP Server | Native Anthropic integration |
463
+ | `generic` | `openai` | Any OpenAI-compatible API |
253
464
 
254
- ### Structured Errors (JSON Mode)
465
+ ### Playground
255
466
 
256
- ```json
257
- {
258
- "error": {
259
- "code": "AUTH_REQUIRED",
260
- "message": "Authentication required",
261
- "suggestion": "Run: mutagent auth login"
262
- }
263
- }
467
+ ```bash
468
+ mutagent playground run <prompt-id> --input '{"topic": "AI"}'
469
+ mutagent playground run <prompt-id> --input '{"topic": "AI"}' --stream
470
+ mutagent playground run <prompt-id> --system "You are..." --human "Hello!"
471
+ mutagent playground run <prompt-id> --messages '[{"role":"user","content":"Hi"}]'
472
+ mutagent playground run <prompt-id> --input '{}' --model gpt-4o
473
+ ```
474
+
475
+ ### Platform (Read-Only)
476
+
477
+ ```bash
478
+ # Workspaces
479
+ mutagent workspaces list
480
+ mutagent workspaces get <id>
481
+
482
+ # Providers
483
+ mutagent providers list
484
+ mutagent providers get <id>
485
+ mutagent providers test <id>
486
+
487
+ # Agents
488
+ mutagent agents list
489
+ mutagent agents get <id>
490
+ mutagent agents create --name "Agent" --slug agent --system-prompt "..."
491
+ mutagent agents update <id> --status paused
492
+ mutagent agents delete <id>
493
+ mutagent agents conversations list <agent-id>
264
494
  ```
265
495
 
266
496
  ---
267
497
 
268
- ## 🔌 Framework Integrations
498
+ ## AI-First Usage
269
499
 
270
- ### Supported Frameworks
500
+ Every command supports `--json` for machine-readable output with `_links` to the web dashboard:
271
501
 
272
- | Framework | Package | Description |
273
- |-----------|---------|-------------|
274
- | **Mastra** | `@mastra/core` | Modern AI agent framework with observability |
275
- | **LangChain** | `langchain` | Popular LLM application framework |
276
- | **LangGraph** | `@langchain/langgraph` | Agent workflow framework |
277
- | **Vercel AI SDK** | `ai` | AI SDK for streaming chat UIs |
278
- | **Claude Code SDK** | `@anthropic-ai/claude-code` | Native Anthropic integration |
279
- | **Generic** | `openai` | Any OpenAI-compatible API |
502
+ ```bash
503
+ # Zero-config with env var
504
+ export MUTAGENT_API_KEY="mg_live_xxxx"
280
505
 
281
- ### Integration Output Format
506
+ # Discover commands
507
+ mutagent --help
282
508
 
283
- Integration guides are output as **Markdown with YAML frontmatter** (similar to Claude Skills):
509
+ # JSON output with deep links
510
+ mutagent prompts list --json
511
+ mutagent prompts get <id> --json
284
512
 
285
- ```markdown
286
- ---
287
- name: mutagent-mastra-integration
288
- framework: mastra
289
- version: 1.0.0
290
- ---
513
+ # Inline JSON for create/update (recommended for AI agents)
514
+ mutagent prompts create -d '{"name":"my-prompt","systemPrompt":"...","outputSchema":{...}}'
291
515
 
292
- # MutagenT + Mastra Integration
516
+ # Non-interactive mode
517
+ mutagent prompts list --non-interactive
293
518
 
294
- ## Prerequisites Verification
519
+ # Generate integration code (raw markdown)
520
+ mutagent integrate langchain --raw
295
521
 
296
- ✓ MUTAGENT_API_KEY: sk_live_...xxxx
297
- ✓ MUTAGENT_ENDPOINT: https://api.mutagent.io/v1
298
- ✓ API Connection: Verified
522
+ # Install skill for Claude Code
523
+ mutagent skills install
524
+ ```
299
525
 
300
- ## Installation
526
+ ### JSON Output Format
301
527
 
302
- ```bash
303
- bun add @mutagent/sdk
528
+ ```json
529
+ {
530
+ "data": { "id": 42, "name": "my-prompt", "..." : "..." },
531
+ "_links": {
532
+ "dashboard": "https://app.mutagent.io/prompts/dashboard?prompt=42",
533
+ "api": "/api/prompts/42",
534
+ "datasets": "https://app.mutagent.io/prompts/dashboard?prompt=42&tab=datasets",
535
+ "evaluations": "https://app.mutagent.io/prompts/dashboard?prompt=42&tab=evaluations"
536
+ }
537
+ }
304
538
  ```
305
539
 
306
- ## Configuration
540
+ ### Exit Codes
541
+
542
+ | Code | Meaning |
543
+ |------|---------|
544
+ | `0` | Success |
545
+ | `1` | General error |
546
+ | `2` | Authentication required |
547
+ | `3` | Configuration error |
548
+ | `5` | Network error |
549
+ | `6` | Rate limit exceeded |
550
+ | `8` | Permission error |
551
+
552
+ ---
307
553
 
308
- MutagenT CLI merges configuration in this order (highest → lowest priority):
554
+ ## State Tracking
309
555
 
310
- 1. Environment variables
311
- 2. Credentials file (`~/.config/mutagent/credentials.json`)
312
- 3. RC files via `cosmiconfig`
313
- 4. Defaults
556
+ The CLI maintains local state to track your MutagenT workflow:
314
557
 
315
- Supported keys:
316
- - `apiKey`
317
- - `endpoint` (default: `https://api.mutagent.io/v1`)
318
- - `format` (`table` | `json`, default: `table`)
319
- - `timeout` (default: `30000`)
320
- - `defaultWorkspace`
321
- - `defaultOrganization`
558
+ | Artifact | Location | Purpose |
559
+ |----------|----------|---------|
560
+ | **Mutation context** | `.mutagent/mutation-context.md` | Tracks discovered prompts, uploaded resources, optimization history |
561
+ | **Comment markers** | Source files | `MutagenT:START` / `MutagenT:END` markers identifying managed prompts |
562
+ | **Auth status** | `mutagent auth status` | Shows onboarding state, context file status, resource counts |
563
+ | **Claude Code skill** | `.claude/skills/mutagent-cli/SKILL.md` | Teaches AI agents how to use MutagenT CLI |
322
564
 
565
+ ```bash
566
+ # Scan codebase and populate context
567
+ mutagent explore
568
+
569
+ # Check your current state
570
+ mutagent auth status
571
+
572
+ # Install Claude Code skill
573
+ mutagent skills install
323
574
  ```
324
575
 
325
576
  ---
326
577
 
327
- ## 📁 Configuration Files
578
+ ## Configuration
328
579
 
329
580
  ### Environment Variables
330
581
 
331
582
  ```bash
332
- MUTAGENT_API_KEY=sk_live_xxxxxxxx
333
- MUTAGENT_ENDPOINT=https://api.mutagent.io/v1
583
+ MUTAGENT_API_KEY=mg_live_xxxxxxxx
584
+ MUTAGENT_ENDPOINT=https://api.mutagent.io
585
+ MUTAGENT_APP_URL=https://app.mutagent.io
334
586
  ```
335
587
 
336
588
  ### RC Files
337
589
 
338
- Create `.mutagentrc` or `.mutagentrc.json`:
590
+ Create `.mutagentrc.json`:
339
591
 
340
592
  ```json
341
593
  {
342
- "endpoint": "https://api.mutagent.io/v1",
594
+ "endpoint": "https://api.mutagent.io",
343
595
  "format": "table"
344
596
  }
345
597
  ```
346
598
 
347
- Or `mutagent.config.js`:
599
+ ### Persistent Defaults
348
600
 
349
- ```javascript
350
- module.exports = {
351
- endpoint: 'https://api.mutagent.io/v1',
352
- format: 'table',
353
- };
601
+ ```bash
602
+ mutagent config set workspace <id> # Avoid passing workspace on every command
603
+ mutagent config set org <id> # Required for org-scoped API keys
354
604
  ```
355
605
 
356
606
  ### Global Config
357
607
 
358
- Stored in `~/.config/mutagent/credentials.json` (created by `mutagent auth login`)
608
+ Stored in `~/.config/mutagent/credentials.json` (created by `mutagent auth login`).
359
609
 
360
610
  ---
361
611
 
362
- ## 🛠️ Development
612
+ ## Migration from Langfuse
613
+
614
+ ```typescript
615
+ // Before (Langfuse)
616
+ import { Langfuse } from 'langfuse';
617
+ const langfuse = new Langfuse({
618
+ publicKey: process.env.LANGFUSE_PUBLIC_KEY,
619
+ secretKey: process.env.LANGFUSE_SECRET_KEY,
620
+ });
621
+
622
+ // After (MutagenT)
623
+ import { initTracing } from '@mutagent/sdk/tracing';
624
+ initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
625
+
626
+ // Framework-specific: use integration packages
627
+ import { MutagentCallbackHandler } from '@mutagent/langchain';
628
+ const handler = new MutagentCallbackHandler();
629
+ ```
630
+
631
+ ---
632
+
633
+ ## Development
363
634
 
364
635
  ### Prerequisites
365
636
 
@@ -374,71 +645,39 @@ cd mutagent-cli
374
645
  bun install
375
646
  ```
376
647
 
377
- ### Development Commands
648
+ ### Commands
378
649
 
379
650
  ```bash
380
- # Run in development mode
381
- bun run dev -- --help
382
-
383
- # Type check
384
- bun run typecheck
385
-
386
- # Build
387
- bun run build
388
-
389
- # Test
390
- bun test
391
- ```
392
-
393
- ---
394
-
395
- ## 🔄 Migration from Langfuse
396
-
397
- Replace Langfuse with MutagenT:
398
-
399
- ```typescript
400
- // Before (Langfuse)
401
- import { Langfuse } from 'langfuse';
402
-
403
- const langfuse = new Langfuse({
404
- publicKey: process.env.LANGFUSE_PUBLIC_KEY,
405
- secretKey: process.env.LANGFUSE_SECRET_KEY,
406
- });
407
-
408
- // After (MutagenT)
409
- import { MutagentObserver } from '@mutagent/sdk/mastra';
410
-
411
- const observer = new MutagentObserver({
412
- apiKey: process.env.MUTAGENT_API_KEY,
413
- });
651
+ bun run dev # Run in development mode
652
+ bun run build # Build
653
+ bun run typecheck # Type check
654
+ bun run lint # Lint
655
+ bun run lint:fix # Lint with auto-fix
656
+ bun run test # Run all tests (574+ tests)
657
+ bun run verify # Full verification (lint + typecheck + build + test)
414
658
  ```
415
659
 
416
660
  ---
417
661
 
418
- ## 📖 Documentation
662
+ ## Documentation
419
663
 
420
664
  - [Full Documentation](https://docs.mutagent.io)
421
- - [API Reference](https://docs.mutagent.io/api)
422
- - [Framework Guides](https://docs.mutagent.io/frameworks)
423
-
424
- ---
425
-
426
- ## 🤝 Contributing
427
-
428
- Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
665
+ - [CLI Commands Reference](https://docs.mutagent.io/cli/commands)
666
+ - [Integration Guides](https://docs.mutagent.io/integrations/overview)
667
+ - [Tracing Setup](https://docs.mutagent.io/tracing/setup)
429
668
 
430
669
  ---
431
670
 
432
- ## 📄 License
671
+ ## License
433
672
 
434
673
  This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
435
674
 
436
- © 2026 MutagenT. All rights reserved.
675
+ (c) 2026 MutagenT. All rights reserved.
437
676
 
438
677
  ---
439
678
 
440
679
  <p align="center">
441
- <sub>Built with ❤️ by the MutagenT Team</sub>
680
+ <sub>Built with care by the MutagenT Team</sub>
442
681
  </p>
443
682
 
444
683
  <p align="center">