@mutagent/cli 0.1.0

package/README.md

@@ -0,0 +1,447 @@
+# MutagenT CLI
+
+```bash
+╔══════════════════════════════════════════════════════════════════════════════════╗
+║                                                                                  ║
+║   ███╗   ███╗██╗   ██╗████████╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗      ║
+║   ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝      ║
+║   ██╔████╔██║██║   ██║   ██║   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║         ║
+║   ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║         ║
+║   ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║         ║
+║   ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝         ║
+║                                                                                  ║
+║                    ██████╗██╗     ██╗                                            ║
+║                   ██╔════╝██║     ██║                                            ║
+║                   ██║     ██║     ██║                                            ║
+║                   ██║     ██║     ██║                                            ║
+║                   ╚██████╗███████╗██║                                            ║
+║                    ╚═════╝╚══════╝╚═╝                                            ║
+║                                                                                  ║
+║                 AI-Native Prompt Optimization Platform.                          ║
+║                                                                                  ║
+╚══════════════════════════════════════════════════════════════════════════════════╝
+```
+
+<p align="center">
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.1+-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-18+-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>Replace Langfuse. Optimize Prompts. 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
+- 📊 **Langfuse Replacement**: Native trace observability without external dependencies
+- 🤖 **AI-First Design**: Every command supports `--json` 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)
+
+---
+
+## 📦 Installation
+
+### Using Bun (Recommended)
+
+```bash
+bun install -g @mutagent/cli
+```
+
+### Using npm
+
+```bash
+npm install -g @mutagent/cli
+```
+
+### Using pnpm
+
+```bash
+pnpm add -g @mutagent/cli
+```
+
+### Verify Installation
+
+```bash
+mutagent --version
+```
+
+---
+
+## 🔑 Quick Start
+
+### 1. Authenticate
+
+```bash
+mutagent auth login
+# Enter your API key when prompted
+```
+
+Or use environment variables:
+
+```bash
+export MUTAGENT_API_KEY="sk_live_xxxxxxxx"
+export MUTAGENT_ENDPOINT="https://api.mutagent.io/v1"
+```
+
+### 2. Check Status
+
+```bash
+mutagent auth status
+```
+
+### 3. Get Framework Integration
+
+```bash
+# Interactive selection
+mutagent integrate
+
+# Direct framework
+mutagent integrate mastra
+mutagent integrate langchain
+mutagent integrate vercel-ai
+```
+
+### 4. Start Using
+
+```bash
+# List prompts
+mutagent prompts list
+
+# Create a prompt
+mutagent prompts create --file ./my-prompt.json
+
+# Run optimization
+mutagent prompts optimize <prompt-id> --dataset <dataset-id>
+
+# View traces (replaces Langfuse)
+mutagent traces list --prompt <prompt-id>
+```
+
+---
+
+## 📚 Commands Reference
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output results as JSON (for AI agents) |
+| `--api-key <key>` | MutagenT API key |
+| `--endpoint <url>` | MutagenT server endpoint |
+| `--help` | Display help for command |
+| `--version` | Display version number |
+
+### Authentication
+
+```bash
+mutagent auth login              # Interactive login
+mutagent auth status             # Check authentication
+mutagent auth logout             # Clear credentials
+```
+
+### Configuration
+
+```bash
+mutagent config list             # List all configuration
+mutagent config get <key>        # Get specific config value
+```
+
+### Prompts
+
+Prompts are the root entity. Datasets, evaluations, and optimizations are scoped to prompts.
+
+```bash
+# CRUD Operations
+mutagent prompts list                           # List all prompts
+mutagent prompts get <id>                       # Get prompt details
+mutagent prompts get <id> --with-datasets       # Include datasets
+mutagent prompts get <id> --with-evals          # Include evaluations
+mutagent prompts create --file prompt.json      # Create from file
+mutagent prompts create --name "My Prompt" --content "..."
+mutagent prompts update <id> --file prompt.json
+mutagent prompts delete <id>
+
+# Datasets (scoped to prompt)
+mutagent prompts datasets <prompt-id>                    # List datasets
+mutagent prompts datasets:add <id> --file data.jsonl     # Add dataset
+mutagent prompts datasets:remove <id> <dataset-id>       # Remove dataset
+
+# Evaluations (scoped to prompt + dataset)
+mutagent prompts evals <prompt-id>                       # List evaluations
+mutagent prompts evals:run <id> --dataset <dataset-id>   # Run evaluation
+mutagent prompts evals:results <run-id>                  # Get results
+
+# Optimization (scoped to prompt + dataset)
+mutagent prompts optimize <id> --dataset <dataset-id>    # Start optimization
+mutagent prompts optimize:status <job-id>                # Check status
+mutagent prompts optimize:results <job-id>               # Get results
+```
+
+### Traces (Langfuse Replacement)
+
+```bash
+mutagent traces list                      # List all traces
+mutagent traces list --prompt <id>        # Filter by prompt
+mutagent traces get <trace-id>            # Get trace details
+mutagent traces analyze <prompt-id>       # Analyze trace patterns
+mutagent traces export --format json      # Export as JSON
+mutagent traces export --format csv       # Export as CSV
+```
+
+### Framework Integration
+
+```bash
+# List available frameworks
+mutagent integrate list
+
+# Get integration guide (markdown format)
+mutagent integrate mastra
+mutagent integrate langchain
+mutagent integrate langgraph
+mutagent integrate vercel-ai
+mutagent integrate claude-code
+mutagent integrate generic
+
+# Save to file
+mutagent integrate mastra --output ./INTEGRATION.md
+
+# Raw markdown output
+mutagent integrate mastra --raw
+
+# Verify integration
+mutagent integrate mastra --verify
+```
+
+---
+
+## 🤖 AI-First Usage
+
+Every command supports `--json` for machine-readable output:
+
+```bash
+# AI agent checking available prompts
+mutagent --json prompts list
+
+# AI agent creating a prompt
+mutagent --json prompts create --file prompt.json
+
+# AI agent running evaluation
+mutagent --json prompts evals:run <id> --dataset <ds-id>
+
+# AI agent getting integration guide
+mutagent --json integrate mastra
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Error |
+| `2` | Partial success / Authentication required |
+
+### Structured Errors (JSON Mode)
+
+```json
+{
+  "error": {
+    "code": "AUTH_REQUIRED",
+    "message": "Authentication required",
+    "suggestion": "Run: mutagent auth login"
+  }
+}
+```
+
+---
+
+## 🔌 Framework Integrations
+
+### Supported Frameworks
+
+| Framework | Package | Description |
+|-----------|---------|-------------|
+| **Mastra** | `@mastra/core` | Modern AI agent framework with observability |
+| **LangChain** | `langchain` | Popular LLM application framework |
+| **LangGraph** | `@langchain/langgraph` | Agent workflow framework |
+| **Vercel AI SDK** | `ai` | AI SDK for streaming chat UIs |
+| **Claude Code SDK** | `@anthropic-ai/claude-code` | Native Anthropic integration |
+| **Generic** | `openai` | Any OpenAI-compatible API |
+
+### Integration Output Format
+
+Integration guides are output as **Markdown with YAML frontmatter** (similar to Claude Skills):
+
+```markdown
+---
+name: mutagent-mastra-integration
+framework: mastra
+version: 1.0.0
+---
+
+# MutagenT + Mastra Integration
+
+## Prerequisites Verification
+
+✓ MUTAGENT_API_KEY: sk_live_...xxxx
+✓ MUTAGENT_ENDPOINT: https://api.mutagent.io/v1
+✓ API Connection: Verified
+
+## Installation
+
+```bash
+bun add @mutagent/sdk
+```
+
+## Configuration
+
+MutagenT CLI merges configuration in this order (highest → lowest priority):
+
+1. Environment variables
+2. Credentials file (`~/.config/mutagent/credentials.json`)
+3. RC files via `cosmiconfig`
+4. Defaults
+
+Supported keys:
+- `apiKey`
+- `endpoint` (default: `https://api.mutagent.io/v1`)
+- `format` (`table` | `json`, default: `table`)
+- `timeout` (default: `30000`)
+- `defaultWorkspace`
+- `defaultOrganization`
+
+```
+
+---
+
+## 📁 Configuration Files
+
+### Environment Variables
+
+```bash
+MUTAGENT_API_KEY=sk_live_xxxxxxxx
+MUTAGENT_ENDPOINT=https://api.mutagent.io/v1
+```
+
+### RC Files
+
+Create `.mutagentrc` or `.mutagentrc.json`:
+
+```json
+{
+  "endpoint": "https://api.mutagent.io/v1",
+  "format": "table"
+}
+```
+
+Or `mutagent.config.js`:
+
+```javascript
+module.exports = {
+  endpoint: 'https://api.mutagent.io/v1',
+  format: 'table',
+};
+```
+
+### Global Config
+
+Stored in `~/.config/mutagent/credentials.json` (created by `mutagent auth login`)
+
+---
+
+## 🛠️ Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.1.0
+- Node.js >= 18.0.0 (fallback)
+
+### Setup
+
+```bash
+git clone https://github.com/mutagent/mutagent-cli.git
+cd mutagent-cli
+bun install
+```
+
+### Development Commands
+
+```bash
+# Run in development mode
+bun run dev -- --help
+
+# Type check
+bun run typecheck
+
+# Build
+bun run build
+
+# Test
+bun test
+```
+
+---
+
+## 🔄 Migration from Langfuse
+
+Replace Langfuse with MutagenT:
+
+```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 { MutagentObserver } from '@mutagent/sdk/mastra';
+
+const observer = new MutagentObserver({
+  apiKey: process.env.MUTAGENT_API_KEY,
+});
+```
+
+---
+
+## 📖 Documentation
+
+- [Full Documentation](https://docs.mutagent.io)
+- [API Reference](https://docs.mutagent.io/api)
+- [Framework Guides](https://docs.mutagent.io/frameworks)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+---
+
+## 📄 License
+
+This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
+
+© 2026 MutagenT. All rights reserved.
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ 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>