mockoon-cli

What this skill does

# Mockoon CLI for API Proxy Testing and Mock Server Management

## Overview

Mockoon CLI is a production-ready Node.js tool that runs sophisticated mock API servers and transparent proxies for API testing, debugging, and development. With over 400,000 downloads and 7,600+ GitHub stars, it's widely used across Fortune 500 companies for API development workflows.

**Core capabilities:**
- Create transparent proxies to real APIs with full traffic logging
- Run mock API servers from configuration files
- Record and analyze API interactions for debugging
- Generate dynamic responses using templating (Faker.js, Handlebars)
- Combine real and mock endpoints (partial mocking)

## Installation

```bash
# Global installation (recommended)
npm install -g @mockoon/cli

# Verify installation
mockoon-cli --version

# Local project installation
npm install --save-dev @mockoon/cli
```

**Requirements:** Node.js 18+ or 20+

## When to Use Mockoon CLI

**For API Testing:**
- Test your application against controllable mock endpoints
- Simulate error scenarios impossible to trigger in production
- Create reproducible test environments without external dependencies

**For Debugging:**
- Proxy traffic to real APIs and log all requests/responses
- Analyze API behavior across microservices architectures
- Trace correlation IDs and debug integration issues

**For Compatibility Layers:**
- Record real API interactions through proxies
- Design adapters between incompatible API versions
- Convert recorded traffic into permanent mocks

## Quick Start Examples

### Basic Mock Server

```bash
# Start a mock from configuration file
mockoon-cli start --data ./mock-config.json --port 3000

# With transaction logging
mockoon-cli start --data ./mock-config.json --port 3000 --log-transaction
```

### Basic API Proxy

```bash
# Create proxy configuration first (see proxy configuration section)
mockoon-cli start --data ./proxy-config.json --port 3000 --log-transaction
```

## Understanding Mockoon Architecture

Mockoon CLI is fundamentally a companion to the Mockoon desktop GUI application. The workflow is:

1. **Design visually** - Use the desktop app's interface to configure mock APIs
2. **Export configuration** - Save as JSON file (Mockoon data format)
3. **Deploy via CLI** - Run those configurations in headless environments

This separation makes Mockoon uniquely accessible—non-technical team members can design APIs visually while developers automate deployment through CI/CD pipelines.

## Creating API Proxies for Testing and Debugging

### Single API Proxy with Full Logging

**Use case:** Debug interactions with `https://api1.example.com` by proxying all traffic through localhost:3000 and logging everything.

**Proxy configuration** (`api1-proxy.json`):

```json
{
  "uuid": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "lastMigration": 29,
  "name": "API1 Proxy",
  "port": 3000,
  "hostname": "0.0.0.0",
  "routes": [],
  "proxyMode": true,
  "proxyHost": "https://api1.example.com",
  "proxyRemovePrefix": false,
  "cors": true,
  "headers": [
    {
      "key": "X-Proxy-By",
      "value": "Mockoon-Debug"
    }
  ]
}
```

**Start the proxy:**

```bash
mockoon-cli start \
  --data ./api1-proxy.json \
  --port 3000 \
  --log-transaction \
  --max-transaction-logs 500
```

**Route traffic through proxy:**

```bash
# Instead of: curl https://api1.example.com/users/123
# Use: curl http://localhost:3000/users/123

curl http://localhost:3000/users/123
curl -X POST http://localhost:3000/orders -d '{"item": "widget"}'
```

**Access logged data:**

```bash
# Get all transaction logs via Admin API
curl http://localhost:3000/mockoon-admin/logs > api1-logs.json

# Analyze with jq
cat api1-logs.json | jq '.transactions[] | select(.request.url | contains("/users"))'

# Count by HTTP method
cat api1-logs.json | jq '.transactions | group_by(.request.method) | map({method: .[0].request.method, count: length})'

# Find slow responses (>1000ms)
cat api1-logs.json | jq '.transactions[] | select(.responseTime > 1000)'
```

### Multiple API Proxies for Microservices

**Use case:** Debug a system with 3 microservices running on different domains.

Create separate proxy configurations for each service, then start all proxies:

```bash
# Background processes
mockoon-cli start --data ./api1-proxy.json --port 3000 --log-transaction &
mockoon-cli start --data ./api2-proxy.json --port 3001 --log-transaction &
mockoon-cli start --data ./api3-proxy.json --port 3002 --log-transaction &
```

**Or use package.json scripts:**

```json
{
  "scripts": {
    "proxy:api1": "mockoon-cli start -d ./api1-proxy.json -p 3000 --log-transaction",
    "proxy:api2": "mockoon-cli start -d ./api2-proxy.json -p 3001 --log-transaction",
    "proxy:api3": "mockoon-cli start -d ./api3-proxy.json -p 3002 --log-transaction",
    "proxy:all": "run-p proxy:api1 proxy:api2 proxy:api3"
  }
}
```

## Partial Mocking: Combining Real and Mock Endpoints

**Use case:** Proxy most traffic to production, but intercept specific problematic endpoints for testing.

```json
{
  "uuid": "partial-mock-001",
  "lastMigration": 29,
  "name": "Partial Mock Proxy",
  "port": 3000,
  "proxyMode": true,
  "proxyHost": "https://api1.example.com",
  "routes": [
    {
      "uuid": "route-001",
      "method": "get",
      "endpoint": "users/90",
      "responses": [
        {
          "uuid": "response-001",
          "statusCode": 200,
          "body": "{\"id\": 90, \"name\": \"Test User\", \"error_case\": true}",
          "headers": [{"key": "Content-Type", "value": "application/json"}]
        }
      ]
    },
    {
      "uuid": "route-002",
      "method": "post",
      "endpoint": "orders",
      "responses": [
        {
          "uuid": "response-002",
          "statusCode": 500,
          "body": "{\"error\": \"Simulated server error\"}",
          "headers": [{"key": "Content-Type", "value": "application/json"}]
        }
      ]
    }
  ]
}
```

**Behavior:**
- `GET /users/90` → Mocked (returns test data)
- `POST /orders` → Mocked (simulates 500 error)
- All other requests → Proxied to api1.example.com

## Dynamic Response Templating

### Request-Based Responses

```json
{
  "routes": [
    {
      "uuid": "dynamic-001",
      "method": "get",
      "endpoint": "users/:userId",
      "responses": [
        {
          "uuid": "resp-001",
          "statusCode": 200,
          "body": "{\"id\": {{urlParam 'userId'}}, \"name\": \"{{faker 'person.fullName'}}\", \"email\": \"{{faker 'internet.email'}}\"}",
          "headers": [{"key": "Content-Type", "value": "application/json"}]
        }
      ]
    }
  ]
}
```

**Available template helpers:**
- `{{urlParam 'name'}}` - Path parameters
- `{{queryParam 'name' 'default'}}` - Query strings
- `{{body 'path.to.field'}}` - Request body properties
- `{{header 'Header-Name'}}` - Request headers
- `{{faker 'category.method'}}` - Generate fake data
- `{{now}}` - Current timestamp
- `{{faker 'string.uuid'}}` - Generate UUID

### Conditional Responses for Error Testing

```json
{
  "routes": [
    {
      "uuid": "conditional-001",
      "method": "post",
      "endpoint": "payments",
      "responses": [
        {
          "uuid": "resp-success",
          "statusCode": 200,
          "body": "{\"status\": \"success\", \"transactionId\": \"{{faker 'string.uuid'}}\"}",
          "rules": [
            {
              "target": "body",
              "modifier": "amount",
              "value": "100",
              "operator": "gte"
            }
          ]
        },
        {
          "uuid": "resp-insufficient",
          "statusCode": 400,
          "body": "{\"error\": \"Insufficient funds\"}",
          "default": true
        }
      ]
    }
  ]
}
```

## Minimal Configuration Structure

```json
{
  "uuid": "unique-environment-id",
  "lastMigration": 29,
  "name": "My Mock API",
  "port": 3000,
  "hostname": "0.0.0.0",
  "routes": [],
  "cors": true
}
```

## Command Reference

### Core Commands

```bash
#