# mrapids CLI: Complete Command Reference & Differentiation
## All Commands at a Glance
| **Getting Started** | `init` | Create project from OpenAPI/GraphQL spec |
| | `explore` | Search/discover operations by keyword |
| | `show` | Display operation details |
| | `validate` | Check spec correctness + linting |
| | `doctor` | Diagnose & auto-fix issues |
| **Execution** | `run` | Execute API operations |
| | `test` | Run automated tests |
| | `list` | List operations/requests |
| **Code Gen** | `gen snippets` | Generate request examples |
| | `gen sdk` | Generate client SDKs (TS, Python, Go, Rust) |
| | `gen stubs` | Generate server stubs |
| | `gen fixtures` | Generate test data |
| | `flatten` | Resolve all $ref references |
| **Auth** | `auth detect` | Auto-detect auth from spec |
| | `auth connect` | Configure credentials |
| | `auth login` | OAuth flow |
| | `auth validate` | Test credentials |
| **Workflows** | `collection run` | Execute request sequences |
| | `collection test` | Run collections as tests |
| | `setup-tests` | Auto-generate test harness |
| **Config** | `env list/show/create` | Manage environments |
| **Analytics** | `db status/query/stats` | DuckDB analytics |
| | `sql` | Query history with SQL |
| | `history` | View past runs |
| | `compare` | Diff two runs (reconciliation) |
| | `export` | Export to Parquet/CSV/JSON |
| **Utilities** | `diff` | Compare specs for breaking changes |
| | `cleanup` | Remove artifacts |
---
## User Workflow: How You Actually Use mrapids
### 1. Start a Project
```bash
# From remote spec
mrapids init my-api --from-url https://api.example.com/openapi.json
# From local file
mrapids init my-api --from-file ./swagger.yaml
```
### 2. Discover What's Available
```bash
# Search for operations
mrapids explore "user"
# List all operations
mrapids list operations
# Show operation details
mrapids show createUser
```
### 3. Execute Operations
```bash
# Simple GET
mrapids run getUser --param userId=123
# POST with body
mrapids run createUser --data '{"name": "John", "email": "john@example.com"}'
# With auth
mrapids run getProfile --profile github
# Don't know the params? Use -Q
mrapids run listUsers -Q
# → Shows all parameters + generates copy-ready command
```
### 4. Query Your History
```bash
# What did I run today?
mrapids history
# SQL queries over all your API calls
mrapids sql "SELECT operation_id, status_code, duration_ms FROM responses WHERE status_code >= 400"
# Compare two runs (regression testing)
mrapids compare --left abc123 --right def456
```
### 5. Automate with Collections
```bash
# Run a workflow
mrapids collection run checkout-flow --var customerId=123
# Export for analysis
mrapids export --table responses --format parquet
```
---
## What Differentiates mrapids from Other Tools
| **Spec-driven execution** | ✅ Native | Import only | ❌ | ❌ | Import only |
| **Parameter discovery (-Q)** | ✅ | Manual | ❌ | ❌ | Manual |
| **Embedded analytics (DuckDB)** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **SQL over API history** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Run comparison/reconciliation** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Agent automation (--json)** | ✅ | Limited | ❌ | ❌ | ❌ |
| **SDK generation** | ✅ Built-in | ❌ | ❌ | ❌ | ❌ |
| **Breaking change detection** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **No GUI required** | ✅ | ❌ | ✅ | ✅ | ❌ |
| **Collections with dependencies** | ✅ | ✅ | ❌ | ❌ | ✅ |
| **Export to Parquet** | ✅ | ❌ | ❌ | ❌ | ❌ |
---
## Key Differentiators Explained
### 1. Spec-Driven Execution (vs. manual request building)
```bash
# Other tools: You manually build every request
curl -X POST https://api.example.com/users -H "Content-Type: application/json" -d '{"name":"..."}'
# mrapids: Spec tells you what's needed
mrapids run createUser -Q
# → Shows required params, auth type, example body
# → Generates copy-ready command
```
**Value**: No guessing. No documentation hunting. The spec is the truth.
### 2. Embedded Analytics (unique to mrapids)
```bash
# Every request is logged to DuckDB
mrapids run getUser --param id=123
# → Stored with timing, headers, response
# Query your history
mrapids sql "SELECT AVG(duration_ms) FROM responses WHERE operation_id = 'getUser'"
# Find slow endpoints
mrapids sql "SELECT endpoint, AVG(duration_ms) as avg_ms FROM responses GROUP BY endpoint ORDER BY avg_ms DESC"
```
**Value**: Your API calls become a queryable dataset. No external tools needed.
### 3. Run Comparison / Reconciliation (unique to mrapids)
```bash
# Run against legacy API
mrapids run getAllProducts --url https://legacy.api.com --json > run1
# → Stores as run_id: abc123
# Run against new API
mrapids run getAllProducts --url https://new.api.com --json > run2
# → Stores as run_id: def456
# Compare
mrapids compare --left abc123 --right def456
# → Shows: status differences, body changes, missing fields
```
**Value**: API migration validation. Regression detection. No manual diffing.
### 4. Agent Automation Mode (vs. human-only tools)
```bash
# Structured output for AI agents / scripts
mrapids run getUser --param id=123 --json
# Returns:
{
"success": true,
"command": "run",
"data": { "status_code": 200, "body": {...} },
"metadata": { "run_id": "abc123", "duration_ms": 142 },
"errors": []
}
```
**Value**: AI agents (Claude, GPT) can parse and act on results. Exit codes are consistent.
### 5. Query Builder (-Q) (vs. reading docs)
```bash
mrapids run users/search -Q
# Output:
┌──────────────────────────────────────────────────────┐
│ users/search GET /users/search │
│ Search for users by criteria │
│ 🔐 Bearer Token │
└──────────────────────────────────────────────────────┘
PARAMETERS:
Name Type Req Description
─────────────────────────────────────────────────────
q string ● Search query
limit int ○ Max results (default: 20)
sort enum ○ [name|created|updated]
COPY & RUN:
mrapids run users/search --auth "Bearer $TOKEN" --param q="john" --param limit=20
```
**Value**: Zero documentation lookup. The command tells you what it needs.
### 6. SDK Generation (built-in, not external)
```bash
mrapids gen sdk --language typescript --output ./sdk
mrapids gen sdk --language python --output ./sdk-py
mrapids gen sdk --language rust --output ./sdk-rs
```
**Value**: No swagger-codegen. No openapi-generator. Single tool.
---
## Summary: When to Use mrapids
| Quick one-off request | `curl` or `httpie` |
| GUI-based exploration | Postman/Insomnia |
| **Spec-driven API testing** | **mrapids** |
| **API history analysis** | **mrapids** |
| **Migration/reconciliation** | **mrapids** |
| **Agent automation** | **mrapids** |
| **CI/CD API validation** | **mrapids** |
**mrapids is not a curl replacement. It's an API operations platform that happens to run from the CLI.**
---
## Detailed Command Reference
### Global Flags (available on all commands)
| `--env <ENV>` | Environment name (dev, staging, prod) |
| `--output-format <FORMAT>` | Output format (json, yaml, table, pretty) |
| `-q, --quiet` | Suppress all output except errors |
| `-v, --verbose` | Enable verbose output |
| `--trace` | Enable trace output (includes HTTP requests/responses) |
| `--no-color` | Disable colored output |
| `--json` | Output as JSON (agent-friendly structured output) |
| `--machine` | Machine-readable mode (no colors, no decorations) |
### Run Command Options
```
mrapids run <OPERATION> [OPTIONS]
Data Input:
-d, --data <JSON> Request body as JSON string or @file.json
-f, --file <PATH> Read request body from file
--stdin Read request body from stdin
Common Parameters:
--id <ID> Resource ID (auto-mapped to path/query)
--name <NAME> Resource name
--status <STATUS> Filter by status
--limit <N> Limit number of results
--offset <N> Offset for pagination
--sort <FIELD> Sort order
Request Parameters:
--param <KEY=VALUE> Set any parameter (can be used multiple times)
--query <KEY=VALUE> Force query parameter
-H, --header <KEY: VALUE> Add HTTP header
Authentication:
--auth <VALUE> Bearer token or Basic auth
--api-key <KEY> API key for X-API-Key header
--profile <PROFILE> Use saved OAuth/auth profile
Testing & Debugging:
--dry-run Preview request without sending
--as-curl Show equivalent curl command
-v, --verbose Show detailed request/response info
--required-only Use only required fields
Query Assistance:
-Q, --build-query Show parameters & copy-ready command
--help-query Show query syntax help
--save-query <NAME> Save current query for reuse
--load-query <NAME> Load a previously saved query
--list-queries List all saved queries
--replay-last Replay last successful query
Agent Automation:
--json-output Output as JSON with run_id and metadata
```
### Auth Subcommands
```
mrapids auth detect [--spec <FILE>] # Auto-detect auth from spec
mrapids auth connect <SCHEME> [OPTIONS] # Configure credentials
mrapids auth login <PROVIDER> [OPTIONS] # OAuth login flow
mrapids auth validate [--scheme <NAME>] # Test credentials
mrapids auth list # List auth profiles
mrapids auth show <PROFILE> # Show profile details
mrapids auth refresh <PROFILE> # Refresh OAuth tokens
mrapids auth logout <PROFILE> # Remove profile
mrapids auth test <PROFILE> # Test authentication
mrapids auth setup <PROVIDER> # Show setup instructions
```
### Database/Analytics Subcommands
```
mrapids db status # Show database status
mrapids db schema [--table <NAME>] # Display schema
mrapids db query "<SQL>" # Run SQL query
mrapids db stats [--operation <ID>] # Show request statistics
mrapids db runs [--limit <N>] # List recent runs
mrapids db run <RUN_ID> # Show run details
mrapids db request <REQUEST_ID> # Show request details
mrapids db check [--fix] # Run health checks
mrapids db migrations # Show migration history
mrapids db reset [--force] # Reset database
```
### SQL Subcommands
```
mrapids sql "<QUERY>" # Run inline SQL
mrapids sql save <NAME> "<QUERY>" # Save query for reuse
mrapids sql run <NAME> [--json|--csv] # Run saved query
mrapids sql list # List saved queries
mrapids sql delete <NAME> # Delete saved query
```
### Collection Subcommands
```
mrapids collection list # List collections
mrapids collection show <NAME> # Show collection details
mrapids collection validate <NAME> # Validate syntax
mrapids collection run <NAME> [OPTIONS] # Execute collection
mrapids collection test <NAME> [OPTIONS] # Run as tests
```
### Gen (Code Generation) Subcommands
```
mrapids gen snippets [--operation <ID>] # Generate examples
mrapids gen sdk --language <LANG> # Generate SDK (ts, python, go, rust)
mrapids gen stubs --framework <FRAMEWORK> # Generate server stubs
mrapids gen fixtures [--count <N>] # Generate test data
```
### Environment Subcommands
```
mrapids env list # List environments
mrapids env show <ENV> # Show environment details
mrapids env create <NAME> [--from <ENV>] # Create environment
mrapids env validate [<ENV>] # Validate configurations
```
---
## Exit Codes
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments / usage error |
| 3 | Authentication error |
| 4 | Network error |
| 5 | Rate limit error |
| 6 | Server error (5xx) |
| 7 | Validation error |
| 8 | Breaking change detected |
---
*Generated: December 22, 2025*