CLI Reference

Usage

mimikos start [flags] <spec-path>
mimikos mcp [flags]

Two commands: start runs a mock server from an OpenAPI spec, mcp runs the MCP server for AI agent integration.

Start flags

Flag	Type	Default	Description
--port	int	8080	Server port
--mode	string	deterministic	Operating mode: deterministic or stateful
--strict	bool	false	Return 500 if a generated response fails schema validation
--max-depth	int	10	Max recursion depth for nested/circular schemas
--max-resources	int	10000	Max stored resources in stateful mode (LRU eviction)
--log-level	string	info	Logging verbosity: debug, info, warn, error

Examples

# Basic — start on default port 8080 with default deterministic mode
mimikos start petstore.yaml

# Custom port
mimikos start --port 3000 petstore.yaml

# Stateful mode with lower capacity
mimikos start --mode stateful --max-resources 500 petstore.yaml

# Strict validation
mimikos start --strict petstore.yaml

# Debug logging
mimikos start --log-level debug petstore.yaml

MCP subcommand

mimikos mcp [flags]

Starts the MCP (Model Context Protocol) server for AI agent integration. The MCP server communicates over stdio and provides 8 tools for controlling mock servers programmatically.

Flag	Type	Default	Description
--log-level	string	info	Logging verbosity: debug, info, warn, error

# Start the MCP server (typically called by your editor, not directly)
mimikos mcp

# With debug logging for diagnostics
mimikos mcp --log-level debug

See the MCP Server page for setup instructions and the full tool reference.

X-Mimikos-Status header

Request a specific response status code from any endpoint:

# Get the 404 response defined in your spec
curl -H "X-Mimikos-Status: 404" http://localhost:8080/pets/42

# Get the 422 response
curl -H "X-Mimikos-Status: 422" http://localhost:8080/pets/42

Behavior:

• Returns the response schema defined in the spec for that status code
• If the status code isn’t defined in the spec for that operation, returns an error listing available codes
• In stateful mode, bypasses all state logic — no reads, no writes, no mutations
• If no response schema exists for the code, returns an RFC 7807 fallback

Tip

Use X-Mimikos-Status to test your client’s error handling against your spec’s actual error schemas — without needing to trigger real error conditions.

OpenAPI compatibility

Feature	Support
OpenAPI 3.0	Supported
OpenAPI 3.1	Supported
YAML specs	Supported
JSON specs	Supported
$ref resolution	Supported (including circular references)
nullable (3.0)	Normalized to 3.1 type: ["...", "null"]
allOf / oneOf / anyOf	Supported
discriminator	Supported
Media type examples	Returned as-is when defined

Other flags

mimikos --version    # Show version
mimikos --help       # Show usage
mimikos start --help # Show start flags
mimikos mcp --help   # Show MCP flags

Alias

The mimik alias is available if you’ve installed via go install and have the symlink set up:

mimik start petstore.yaml

Environment

Mimikos has no environment variable configuration. All settings are passed via CLI flags. This is intentional — a single command with explicit flags is easier to reproduce and debug than implicit environment state.