# aimock CLI

Configure all your mocks in one JSON file and serve them on a single port — LLM providers, MCP, A2A, AG-UI, vector databases, and services.

## Quick Start

Run aimock shell

    $ npx @copilotkit/aimock --config aimock.json --port 4010

Run aimock shell

    # --config is an aimock-CLI feature, not available in the published image.
    # Run aimock on your host via npx (or install @copilotkit/aimock in your
    # own container image) to use the config-driven CLI:
    $ npx @copilotkit/aimock --config aimock.json --port 4010 --host 0.0.0.0

    # If you only need flag-driven fixture serving, the published image works:
    $ docker run -d -p 4010:4010 \
      -v ./fixtures:/fixtures \
      ghcr.io/copilotkit/aimock \
      -f /fixtures -h 0.0.0.0

Note: The published Docker image (`ghcr.io/copilotkit/aimock`) runs the flag-driven `llmock` CLI (ENTRYPOINT `node dist/cli.js`), which does not support `--config` or the `convert` subcommand. For config-driven mode, run aimock on your host via `npx` or install `@copilotkit/aimock` inside your own image.

## Config File Format

The config file is a JSON object describing which services to run and how to configure them. The `llm` section configures the core LLMock server. Additional services are mounted at path prefixes.

aimock.json json

    {
      "llm": {
        "fixtures": "./fixtures",
        "latency": 0,
        "chunkSize": 20,
        "logLevel": "info",
        "validateOnLoad": true,
        "metrics": true,
        "strict": false
      },
      "services": {
        "/mcp": {
          "type": "mcp",
          "tools": "./mcp-tools.json"
        },
        "/a2a": {
          "type": "a2a",
          "agents": "./a2a-agents.json"
        }
      }
    }

### Config Fields

Field | Type | Description
--- | --- | ---
`llm` | object | LLMock configuration. Accepts `fixtures`, `latency`, `chunkSize`, `logLevel`, `validateOnLoad`, `metrics`, `strict`, `chaos`, `streamingProfile`, `record`.
`services` | object | Map of mount paths to service configs. Each key is a URL path prefix (e.g. `/mcp`), each value describes the service type and its options.

### Recording Config (`llm.record`)

When `llm.record` is present, aimock proxies unmatched requests to real providers and saves the responses as fixtures. See Record & Replay for full details.

Option | Type | Default | Description
--- | --- | --- | ---
`providers` | object | — | Map of provider names to upstream URLs or API keys (e.g. `{ "openai": "sk-..." }`)
`fixturePath` | string | `./fixtures/recorded` | Directory where recorded fixtures are saved
`proxyOnly` | boolean | `false` | Proxy without saving fixtures to disk or caching in memory
`recordFullModelVersion` | boolean | `false` | Record the exact model string without stripping date/version suffixes. Use when tests depend on exact model version matching. See Model-Aware Recording

Recording config example json

    {
      "llm": {
        "fixtures": "./fixtures",
        "record": {
          "providers": {
            "openai": "https://api.openai.com",
            "anthropic": "https://api.anthropic.com"
          },
          "fixturePath": "./fixtures/recorded",
          "recordFullModelVersion": false
        }
      }
    }

## CLI Flags

Option | Default | Description
--- | --- | ---
`--config` | `aimock.json` | Path to JSON config file
`--port` | `4010` | Port to listen on (overrides config)
`--host` | `127.0.0.1` | Host to bind to (overrides config)
`--help` | — | Show help

## Single-Port Routing

All services share one port. Requests are routed by path prefix. LLM endpoints live at the root, mounted services at their configured prefix:

Path | Service
--- | ---
`/v1/chat/completions` | LLMock (OpenAI Chat Completions)
`/v1/messages` | LLMock (Anthropic Claude)
`/v1/embeddings` | LLMock (Embeddings)
`/mcp/*` | MCP mock service
`/a2a/*` | A2A mock service
`/health` | Unified health check (all services)
`/metrics` | Prometheus metrics (if enabled)

Path stripping is automatic — a request to `/mcp/tools/list` arrives at the MCP service as `/tools/list`.

## Docker Usage

Run with config shell

    $ npx @copilotkit/aimock --config aimock.json --host 0.0.0.0

Run with config (local / npx) shell

    # --config isn't available in the published Docker image's llmock entrypoint.
    # Run aimock locally with npx to load config.json:
    $ npx @copilotkit/aimock --config aimock.json --host 0.0.0.0

## Fixture Converters

Convert fixtures from other mock tools to aimock format.

### Usage

Convert fixtures shell

    npx @copilotkit/aimock convert <format> <input> [output]

### Supported Formats

Format | Source | Description
--- | --- | ---
`vidaimock` | VidaiMock Tera templates | Converts `.tera` / `.json` / `.txt` templates to aimock fixture JSON
`mockllm` | mock-llm YAML config | Converts mock-llm YAML configs to aimock fixture JSON. Also extracts MCP tools if present.

### Examples

Converter examples shell

    # Convert a directory of VidaiMock templates
    $ npx @copilotkit/aimock convert vidaimock ./templates/ ./fixtures/converted.json

    # Convert a mock-llm YAML config
    $ npx @copilotkit/aimock convert mockllm ./config.yaml ./fixtures/converted.json

    # Print to stdout (omit output path)
    $ npx @copilotkit/aimock convert vidaimock ./templates/

## Docker Compose

The published image's ENTRYPOINT runs the flag-driven `llmock` CLI — it supports `-f/--fixtures`, `-p/--port`, `-h/--host`, and the chaos / record flags, but not `--config`. Use the compose snippet below for flag-driven fixture serving. For full config-driven mode (LLM + MCP + A2A + AG-UI on one port), either build your own image with `@copilotkit/aimock` installed, or run `npx @copilotkit/aimock --config ...` on the host.

docker-compose.yml yaml

    services:
      aimock:
        image: ghcr.io/copilotkit/aimock:latest
        command: ["-f", "/app/fixtures", "-h", "0.0.0.0"]
        ports:
          - "4010:4010"
        volumes:
          - ./fixtures:/app/fixtures:ro

      app:
        build: .
        environment:
          OPENAI_BASE_URL: http://aimock:4010/v1
        depends_on:
          - aimock