CLI Reference

MockForge provides a comprehensive command-line interface for managing mock servers and generating test data. This reference covers all available commands, options, and usage patterns.

Commands

`serve` - Start Mock Servers

The primary command for starting MockForge’s mock servers with support for HTTP, WebSocket, and gRPC protocols.

mockforge-cli serve [OPTIONS]

Server Options

Port Configuration:

--http-port <PORT>: HTTP server port (default: 3000)
--ws-port <PORT>: WebSocket server port (default: 3001)
--grpc-port <PORT>: gRPC server port (default: 50051)

API Specification:

--spec <PATH>: OpenAPI spec file for HTTP server (JSON or YAML format)

Configuration:

-c, --config <PATH>: Path to configuration file

Admin UI Options

Admin UI Control:

--admin: Enable admin UI
--admin-port <PORT>: Admin UI port (default: 9080)
--admin-embed: Force embedding Admin UI under HTTP server
--admin-mount-path <PATH>: Explicit mount path for embedded Admin UI (implies --admin-embed)
--admin-standalone: Force standalone Admin UI on separate port (overrides embed)
--disable-admin-api: Disable Admin API endpoints (UI loads but API routes are absent)

Validation Options

Request Validation:

--validation <MODE>: Request validation mode (default: enforce)
- off: Disable validation
- warn: Log warnings but allow requests
- enforce: Reject invalid requests
--aggregate-errors: Aggregate request validation errors into JSON array
--validate-responses: Validate responses (warn-only)
--validation-status <CODE>: Validation error HTTP status code (default: 400)

Response Processing

Template Expansion:

--response-template-expand: Expand templating tokens in responses/examples

Chaos Engineering

Latency Simulation:

--latency-enabled: Enable latency simulation

Failure Injection:

--failures-enabled: Enable failure injection

Examples

Basic HTTP Server:

mockforge-cli serve --spec examples/openapi-demo.json --http-port 3000

Full Multi-Protocol Setup:

mockforge-cli serve \
  --spec examples/openapi-demo.json \
  --http-port 3000 \
  --ws-port 3001 \
  --grpc-port 50051 \
  --admin \
  --admin-port 9080 \
  --response-template-expand

Development Configuration:

mockforge-cli serve \
  --config demo-config.yaml \
  --validation warn \
  --response-template-expand \
  --latency-enabled

Production Configuration:

mockforge-cli serve \
  --config production-config.yaml \
  --validation enforce \
  --admin-standalone

`init` - Initialize New Project

Create a new MockForge project with a template configuration file.

mockforge-cli init [OPTIONS] <NAME>

Arguments

<NAME>: Project name or directory path
- Use . to initialize in the current directory
- Use a project name to create a new directory

Options

--no-examples: Skip creating example files (only create mockforge.yaml)

Examples

# Create a new project in a new directory
mockforge-cli init my-mock-api

# Initialize in the current directory
mockforge-cli init .

# Initialize without examples
mockforge-cli init my-project --no-examples

What Gets Created

mockforge.yaml: Main configuration file with:
- HTTP, WebSocket, gRPC server configurations
- Admin UI settings
- Core features (latency, failures, overrides)
- Observability configuration
- Data generation settings
- Logging configuration
examples/ directory (unless --no-examples):
- openapi.json: Sample OpenAPI specification
- Example data files

`config` - Configuration Management

Validate and manage MockForge configuration files.

mockforge-cli config <SUBCOMMAND>

Subcommands

`validate` - Validate Configuration File

Validate a MockForge configuration file for syntax and structure errors.

mockforge-cli config validate [OPTIONS]

Options:

--config <PATH>: Path to config file to validate
- If omitted, auto-discovers mockforge.yaml or mockforge.yml in current and parent directories

What Gets Validated:

YAML syntax and structure
File existence
HTTP endpoints count
Request chains count
Missing sections (warnings)

Examples:

# Validate config in current directory
mockforge-cli config validate

# Validate specific config file
mockforge-cli config validate --config my-config.yaml

# Validate before starting server
mockforge-cli config validate && mockforge-cli serve

Output Example:

🔍 Validating MockForge configuration...
📄 Checking configuration file: mockforge.yaml
✅ Configuration is valid

📊 Summary:
   Found 5 HTTP endpoints
   Found 2 chains

⚠️  Warnings:
   - No WebSocket configuration found

Common Issues:

Invalid YAML syntax: Fix indentation, quotes, or structure
File not found: Check path or run mockforge init
Missing sections: Add HTTP, admin, or other required sections

Note: Current validation is basic (syntax, structure, counts). For comprehensive field validation, see the Configuration Validation Guide.

`data` - Generate Synthetic Data

Generate synthetic test data using various templates and schemas.

mockforge-cli data <SUBCOMMAND>

Subcommands

`template` - Generate from Built-in Templates

Generate data using MockForge’s built-in data generation templates.

mockforge-cli data template [OPTIONS]

Options:

--count <N>: Number of items to generate (default: 1)
--format <FORMAT>: Output format (json, yaml, csv)
--template <NAME>: Template name (user, product, order, etc.)
--output <PATH>: Output file path

Examples:

# Generate 10 user records as JSON
mockforge-cli data template --template user --count 10 --format json

# Generate product data to file
mockforge-cli data template --template product --count 50 --output products.json

`schema` - Generate from JSON Schema

Generate data conforming to a JSON Schema specification.

mockforge-cli data schema [OPTIONS] <SCHEMA>

Parameters:

<SCHEMA>: Path to JSON Schema file

Options:

--count <N>: Number of items to generate (default: 1)
--format <FORMAT>: Output format (json, yaml)
--output <PATH>: Output file path

Examples:

# Generate data from user schema
mockforge-cli data schema --count 5 user-schema.json

# Generate and save to file
mockforge-cli data schema --count 100 --output generated-data.json api-schema.json

`open-api` - Generate from OpenAPI Spec

Generate mock data based on OpenAPI specification schemas.

mockforge-cli data open-api [OPTIONS] <SPEC>

Parameters:

<SPEC>: Path to OpenAPI specification file

Options:

--endpoint <PATH>: Specific endpoint to generate data for
--method <METHOD>: HTTP method (get, post, put, delete)
--count <N>: Number of items to generate (default: 1)
--format <FORMAT>: Output format (json, yaml)
--output <PATH>: Output file path

Examples:

# Generate data for all endpoints in OpenAPI spec
mockforge-cli data open-api api-spec.yaml

# Generate data for specific endpoint
mockforge-cli data open-api --endpoint /users --method get --count 20 api-spec.yaml

# Generate POST request body data
mockforge-cli data open-api --endpoint /users --method post api-spec.yaml

`admin` - Admin UI Server

Start the Admin UI as a standalone server without the main mock servers.

mockforge-cli admin [OPTIONS]

Options

--port <PORT>: Server port (default: 9080)

Examples

# Start admin UI on default port
mockforge-cli admin

# Start admin UI on custom port
mockforge-cli admin --port 9090

`bench` - OpenAPI-driven Load Testing

Generate and run a k6 load test from an OpenAPI spec.

mockforge bench --spec api.yaml --target http://localhost:3000 [OPTIONS]

Common Options

-s, --spec <PATH> — OpenAPI spec file (repeatable for multi-spec mode).
--spec-dir <DIR> — Directory of specs (auto-discovered).
-t, --target <URL> — Target server URL.
-d, --duration <SECS> — Run length (default: 60).
--vus <N> — Virtual users (default: 10).
--scenario <NAME> — constant | ramp-up | spike | stress | soak.
--operations <FILTER> — Comma-separated operation filter (e.g. "GET /users,POST /orders").
--auth <HEADER> — Authorization header value (e.g. "Bearer $TOKEN").
--headers <KV> — Comma-separated extra headers (e.g. "X-Tenant: a,X-Region: b").
--threshold-percentile <P> / --threshold-ms <N> — Latency SLO.
--max-error-rate <RATE> — Error-rate SLO (0.01 = 1%).
--generate-only — Write the k6 script without running it.
--script-output <PATH> — Where to write the generated script.
--targets-file <PATH> — Multi-target mode (one URL per line).
--max-concurrency <N> — Parallel target limit (default: 10).
--insecure — Skip TLS verification (test self-signed certs).
--chunked-request-bodies — Add Transfer-Encoding: chunked to every k6 request body. NOTE: k6 runs on Go’s net/http, which may still send Content-Length based on body type. For guaranteed wire chunking use bench-chunked instead.

See the Load Testing chapter for the full options surface (security testing, OWASP API top 10, conformance mode, data-driven testing) and end-to-end examples.

`bench-chunked` - Native Chunked Traffic Generator

Send guaranteed Transfer-Encoding: chunked request bodies via hyper. Useful when bench --chunked-request-bodies falls back to Content-Length (Go’s transport heuristics) and you need real chunked traffic on the wire.

mockforge bench-chunked --target http://localhost:3000/upload [OPTIONS]

Options

--target <URL> — Target URL (required).
--method <METHOD> — POST (default), PUT, or PATCH.
-c, --concurrency <N> — Concurrent workers (default: 10).
-d, --duration <SECS> — Run length (default: 30).
--chunk-size-bytes <N> — Bytes per chunk (default: 1024).
--total-size-bytes <N> — Total body size per request (default: 1048576 = 1 MiB).
--chunk-interval-ms <MS> — Sleep between chunks (default: 0 = back-to-back).
--header <NAME: VALUE> — Extra header (repeatable).
--insecure — Skip TLS verification.

Reports req/s, p50/p95/p99 latency, and a status-code distribution at the end.

`git-watch` - Watch a Git Repo for Spec Changes

Monitor a Git repository for changes to OpenAPI / spec files and automatically reload the local mock server when they change. Useful for teams that store specs in a separate repo from their mock config.

mockforge git-watch https://github.com/user/api-specs \
  --reload-command "mockforge serve --spec"

Common options: --branch, --poll-interval, --auth-token (for private repos), --cache-dir, --spec-paths (comma-separated globs to watch).

`contract-sync` - Sync Contracts from a Git Repo

One-shot pull of OpenAPI / contract specs from a Git repository, with an optional report comparing the new spec against the current mock config.

mockforge contract-sync https://github.com/user/api-specs \
  --update --output report.md

Use --update to overwrite local copies; omit it for a dry-run report. Pairs well with CI — fail the build if the upstream contract drifted from what the mock returns.

`validate-fixtures` - Validate Fixture Files

Lint a directory or single file of fixture data against MockForge’s schema. Useful pre-commit guard for repos that check fixtures into source control.

# Validate every fixture in a directory
mockforge validate-fixtures --dir ./fixtures

# Validate one file
mockforge validate-fixtures --file ./fixtures/users.json

# Verbose mode — show per-fixture details, not just failures
mockforge validate-fixtures --dir ./fixtures --verbose

Exit code 0 on clean, non-zero on any validation failure.

`tui` - Terminal Dashboard

Live dashboard in the terminal showing server status, system metrics (current and lifetime peak CPU / memory / error rate), request stats, and recent logs. Auto-refreshes every 2 s.

mockforge tui

Optionally pair with MOCKFORGE_METRICS_LOG_FILE=path.csv to also append a persistent CSV record while the server runs.

`bench-pipeline` - HTTP Pipelining Load Test

Load-test a target with HTTP pipelining: synthetic request bodies (json / xml / urlencoded / multipart) are written back-to-back per connection before any response is read.

mockforge bench-pipeline --target http://localhost:3000/api \
  --content-type json --body-size 500KB --pipeline-depth 16 \
  --connections 8 --duration 30s

Options

--target <url> (required): plain-http:// target URL.
--method <method>: HTTP method; pipelining is only meaningful with bodies, so the default is POST.
--content-type <flavour>: json | xml | urlencoded | multipart (default json).
--body-size <size>: exact body size per request — bare bytes or KB/MB/GB / KiB/MiB/GiB (default 1KB).
--pipeline-depth <n>: requests in flight per connection before reading responses (default 16).
--connections <n>: concurrent connections (default 8).

`verify-mocks` - Mock Fidelity / Drift Detection

Compare the mocks generated from an OpenAPI spec against real captured traffic in a recorder database, and report drift: endpoints whose mocks no longer match how clients actually call them.

mockforge verify-mocks --spec openapi.json --capture-db recorder.sqlite

Options

--spec <path> (required): OpenAPI spec the mocks were generated from (3.x natively; Swagger 2.0 is up-converted automatically).
--capture-db <path> (required): recorder SQLite database holding captured traffic (what mockforge record writes).
--limit <n>: maximum exchanges to evaluate, oldest first (default 500).
--fail-on-drift: exit with code 1 when any drift is found — use as a CI gate.
--output <path>: write the structured drift report as JSON.

`sync` - Workspace Synchronization Daemon

Start a background daemon that monitors a workspace directory for file changes and automatically syncs them to MockForge workspaces.

mockforge-cli sync [OPTIONS]

Options

Required:

--workspace-dir <PATH> or -w <PATH>: Workspace directory to monitor for changes

Optional:

--config <PATH> or -c <PATH>: Configuration file path for sync settings

How It Works

The sync daemon provides bidirectional synchronization between workspace files and MockForge’s internal workspace storage:

File Monitoring: Watches for .yaml and .yml files in the workspace directory
Automatic Import: When files are created or modified, they’re automatically imported into the workspace
Real-time Updates: Changes are detected and processed immediately
Visual Feedback: Clear console output shows what’s happening in real-time

File Requirements:

Only .yaml and .yml files are monitored
Hidden files (starting with .) are ignored
Files must be valid MockRequest YAML format

What You’ll See:

File creation notifications with import status
File modification notifications with update status
File deletion notifications (files are not auto-deleted from workspace)
Error messages if imports fail
Real-time feedback for all sync operations

Examples

Basic Usage:

# Start sync daemon for a workspace directory
mockforge-cli sync --workspace-dir ./my-workspace

# Use short form
mockforge-cli sync -w ./my-workspace

# With custom config
mockforge-cli sync --workspace-dir /path/to/workspace --config sync-config.yaml

Git Integration:

# Monitor a Git repository directory
mockforge-cli sync --workspace-dir /path/to/git/repo/workspaces

# Changes you make in Git will automatically sync to MockForge
# Perfect for team collaboration via Git

Development Workflow:

# 1. Start the sync daemon in one terminal
mockforge-cli sync --workspace-dir ./workspaces

# 2. In another terminal, edit workspace files
vim ./workspaces/my-request.yaml

# 3. Save the file - it will automatically import to MockForge
# You'll see output like:
#   🔄 Detected 1 file change in workspace 'default'
#     📝 Modified: my-request.yaml
#        ✅ Successfully updated

Example Output

When you start the sync daemon, you’ll see:

🔄 Starting MockForge Sync Daemon...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 Workspace directory: ./my-workspace

ℹ️  What the sync daemon does:
   • Monitors the workspace directory for .yaml/.yml file changes
   • Automatically imports new or modified request files
   • Syncs changes bidirectionally between files and workspace
   • Skips hidden files (starting with .)

🔍 Monitoring for file changes...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Sync daemon started successfully!
💡 Press Ctrl+C to stop

📂 Monitoring workspace 'default' in directory: ./my-workspace

When files change, you’ll see:

🔄 Detected 1 file change in workspace 'default'
  ➕ Created: new-endpoint.yaml
     ✅ Successfully imported

🔄 Detected 2 file changes in workspace 'default'
  📝 Modified: user-api.yaml
     ✅ Successfully updated
  🗑️  Deleted: old-endpoint.yaml
     ℹ️  Auto-deletion from workspace is disabled

If errors occur:

🔄 Detected 1 file change in workspace 'default'
  📝 Modified: invalid-file.yaml
     ⚠️  Failed to import: File is not a recognized format (expected MockRequest YAML)

Stopping the Daemon

Press Ctrl+C to gracefully stop the sync daemon:

^C
🛑 Received shutdown signal
⏹️  Stopped monitoring workspace 'default' in directory: ./my-workspace
👋 Sync daemon stopped

Best Practices

Version Control:

# Use sync with Git for team collaboration
cd /path/to/git/repo
mockforge-cli sync --workspace-dir ./workspaces

# Team members can push/pull changes
# The sync daemon will automatically import updates

Development Workflow:

# Keep sync daemon running during development
# Edit files in your favorite editor
# Changes automatically sync to MockForge
# Perfect for file-based workflows

Directory Organization:

# Organize workspace files in subdirectories
workspaces/
├── api-v1/
│   ├── users.yaml
│   └── products.yaml
├── api-v2/
│   └── users.yaml
└── internal/
    └── admin.yaml

# All .yaml files will be monitored
mockforge-cli sync --workspace-dir ./workspaces

Troubleshooting

Files not importing:

Ensure files have .yaml or .yml extension
Check that files are valid MockRequest YAML format
Look for error messages in the console output
Verify files are not hidden (don’t start with .)

Permission errors:

Ensure MockForge has read access to the workspace directory
Check file permissions: ls -la workspace-dir/

Changes not detected:

The sync daemon uses filesystem notifications
Some network filesystems may not support change notifications
Try editing the file locally rather than over a network mount

Enable debug logging:

RUST_LOG=mockforge_core::sync_watcher=debug mockforge-cli sync --workspace-dir ./workspace

Configuration File Format

MockForge supports YAML configuration files that can be used instead of command-line options.

Basic Configuration Structure

# Server configuration
server:
  http_port: 3000
  ws_port: 3001
  grpc_port: 50051

# API specification
spec: examples/openapi-demo.json

# Admin UI configuration
admin:
  enabled: true
  port: 9080
  embedded: false
  mount_path: "/admin"
  standalone: true
  disable_api: false

# Validation settings
validation:
  mode: enforce
  aggregate_errors: false
  validate_responses: false
  status_code: 400

# Response processing
response:
  template_expand: true

# Chaos engineering
chaos:
  latency_enabled: false
  failures_enabled: false

# Protocol-specific settings
grpc:
  proto_dir: "proto/"
  enable_reflection: true

websocket:
  replay_file: "examples/ws-demo.jsonl"

Configuration Precedence

Configuration values are applied in the following order (later sources override earlier ones):

Default values (compiled into the binary)
Configuration file (-c/--config option)
Environment variables
Command-line arguments (highest priority)

Environment Variables

All configuration options can be set via environment variables using the MOCKFORGE_ prefix:

# Server ports
export MOCKFORGE_HTTP_PORT=3000
export MOCKFORGE_WS_PORT=3001
export MOCKFORGE_GRPC_PORT=50051

# Admin UI
export MOCKFORGE_ADMIN_ENABLED=true
export MOCKFORGE_ADMIN_PORT=9080

# WebSocket settings
export MOCKFORGE_WS_REPLAY_FILE=examples/ws-demo.jsonl

# gRPC settings
export MOCKFORGE_PROTO_DIR=proto/

# Data generation (RAG)
export MOCKFORGE_RAG_ENABLED=true
export MOCKFORGE_RAG_PROVIDER=openai
export MOCKFORGE_RAG_API_KEY=your-api-key

For the full env-var surface, see Environment Variables. Plugin system, admin auth, encryption, sync daemon, and validation toggles are configured via YAML rather than env vars; see the relevant chapter for each.

Exit Codes

MockForge uses standard exit codes:

0: Success
1: General error
2: Configuration error
3: Validation error
4: File I/O error
5: Network error

Logging

MockForge provides configurable logging output to help with debugging and monitoring.

Log Levels

error: Only error messages
warn: Warnings and errors
info: General information (default)
debug: Detailed debugging information
trace: Very verbose tracing information

Log Configuration

# Set log level via environment variable
export RUST_LOG=mockforge=debug

# Or via configuration file
logging:
  level: debug
  format: json

Log Output

Logs include structured information about:

HTTP requests/responses
WebSocket connections and messages
gRPC calls and streaming
Configuration loading
Template expansion
Validation errors

Examples

Complete Development Setup

# Start all servers with admin UI
mockforge-cli serve \
  --spec examples/openapi-demo.json \
  --http-port 3000 \
  --ws-port 3001 \
  --grpc-port 50051 \
  --admin \
  --admin-port 9080 \
  --response-template-expand \
  --validation warn

CI/CD Testing Pipeline

#!/bin/bash
# test-mockforge.sh

# Start MockForge in background
mockforge-cli serve --spec api-spec.yaml --http-port 3000 &
SERVER_PID=$!

# Wait for server to start
sleep 5

# Run API tests
npm test

# Generate test data
mockforge-cli data open-api --endpoint /users --count 100 api-spec.yaml > test-users.json

# Stop MockForge
kill $SERVER_PID

Load Testing Setup

#!/bin/bash
# load-test-setup.sh

# Start MockForge with minimal validation for performance
MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=false \
mockforge-cli serve \
  --spec load-test-spec.yaml \
  --http-port 3000 \
  --validation off

# Now run your load testing tool against localhost:3000
# Example: hey -n 10000 -c 100 http://localhost:3000/api/test

Docker Integration

# Run MockForge in Docker with CLI commands
docker run --rm -v $(pwd)/examples:/examples \
  mockforge \
  serve --spec /examples/openapi-demo.json --http-port 3000

Troubleshooting

Common Issues

Server won’t start:

# Check if ports are available
lsof -i :3000
lsof -i :3001

# Try different ports
mockforge-cli serve --http-port 3001 --ws-port 3002

Configuration not loading:

# Validate YAML syntax
yamllint config.yaml

# Check file permissions
ls -la config.yaml

OpenAPI spec not found:

# Verify file exists and path is correct
ls -la examples/openapi-demo.json

# Use absolute path
mockforge-cli serve --spec /full/path/to/examples/openapi-demo.json

Template expansion not working:

# Ensure template expansion is enabled
mockforge-cli serve --response-template-expand --spec api-spec.yaml

Debug Mode

Run with debug logging for detailed information:

RUST_LOG=mockforge=debug mockforge-cli serve --spec api-spec.yaml

Health Checks

Test basic functionality:

# HTTP health check
curl http://localhost:3000/health

# WebSocket connection test
websocat ws://localhost:3001/ws

# gRPC service discovery
grpcurl -plaintext localhost:50051 list

This CLI reference provides comprehensive coverage of MockForge’s command-line interface. For programmatic usage, see the Rust API Reference.

MockForge Documentation