CLI Reference — Mimic Docs

mimic init

Interactive wizard to create a mimic.json configuration.

bash

$ mimic init

Walks you through domain, schema source, database URL, persona selection, and LLM provider. Creates mimic.json plus .mimic/data/ and .mimic/blueprints/ directories.

mimic run

Generate blueprints and expand persona data.

bash

$ mimic run [options]

Options:
  -g, --generate           Force LLM regeneration of blueprints
  -d, --dry-run            Show what would be generated without writing files
  -p, --persona <names...> Limit to specific personas
  -s, --seed <number>      Override random seed
  --verbose                Enable verbose logging

Parses your database schema, generates persona blueprints via LLM (or loads from cache), and expands them into concrete rows. Output is written to .mimic/data/ as JSON files per persona. Blueprints are cached in .mimic/blueprints/ — use -g to force regeneration.

mimic seed

Push expanded data to configured databases.

bash

$ mimic seed [options]

Options:
  -p, --persona <names...> Limit to specific personas
  -s, --strategy <strategy> Override seed strategy (depends on database type)
  -d, --database <name>    Seed a specific database entry
  --verbose                Enable verbose logging
  --json                   Output results as JSON

Loads expanded data from .mimic/data/ and pushes it to your configured databases. Uses COPY FROM STDIN for PostgreSQL (≥500 rows) for high throughput. Handles foreign key ordering via topological sort. Atomic transactions — all or nothing.

mimic host

Start mock API servers and MCP servers to expose seeded data to AI agents.

bash

$ mimic host [options]

Options:
  --mcp-base-port <number>     Starting port for MCP servers (default: 4201)
  --api-base-port <number>     Starting port for mock API servers (default: 4101)
  --no-api                     Skip starting mock API servers
  --verbose                    Enable verbose logging

What it starts

mimic host spins up one server pair per configured database and one server pair per enabled API adapter — there is no single shared server.

For each database in mimic.json:

Connects to the database and parses the schema
Starts an MCP server exposing auto-generated query tools for every table

For each enabled adapter in mimic.json:

Loads persona data from .mimic/data/ and registers it with the adapter
Starts a mock HTTP API server serving realistic responses at the adapter’s base path
Starts an MCP server exposing the adapter’s tools (when mcp: true is set), pointed at the mock API

Port assignment

Ports are assigned sequentially starting from the base port values:

bash

# Example: 1 database + 2 adapters
#   main-db   MCP :4201
#   plaid     API :4101 | MCP :4202
#   stripe    API :4102 | MCP :4203
$ mimic host

Use --mcp-base-port and --api-base-port to shift the port ranges if they conflict with other services.

Transport

All MCP servers use the Streamable HTTP transport (http://localhost:<port>/mcp, per MCP spec 2025-03-26). This allows mimic host to run as a background server that agents connect to over HTTP.

Connection summary

After all servers start, mimic host prints a JSON block of MCP endpoints ready to paste into your agent’s MCP configuration:

bash

{
  "main-db": { "url": "http://localhost:4201/mcp", "type": "database" },
  "plaid":   { "url": "http://localhost:4202/mcp", "type": "adapter" },
  "stripe":  { "url": "http://localhost:4203/mcp", "type": "adapter" }
}

`--no-api` flag

Skips starting mock HTTP API servers for all adapters. MCP servers for adapters are also omitted since they depend on the mock API URL. Only database MCP servers start. Useful when you only need the database tools exposed to your agent.

Graceful shutdown

mimic host blocks the terminal until you press Ctrl+C (or send SIGTERM). On shutdown it stops all MCP servers, mock API servers, and closes all database connections cleanly.

mimic explore

Open the interactive data explorer UI in your browser.

bash

$ mimic explore [options]

Options:
  --port <number>           Port for the explorer UI (default: 7879)
  --no-open                Do not auto-open the browser

Launches a local web UI for browsing and inspecting generated persona data. The explorer reads from .mimic/data/ and presents it in a navigable interface.

Background process

mimic explore spawns the explorer as a detached background process and exits immediately — it does not block your terminal. The background process PID is printed so you can stop it later:

bash

$ mimic explore

  mimic explore
  ✔ Using port 7879
  ✔ Explorer running at http://localhost:7879
  ℹ Background process PID 12345 — to stop: kill 12345

Port selection

By default the explorer uses port 7879. If that port is in use, it automatically finds the next available port. Use --port to specify a custom port.

Browser auto-open

The explorer automatically opens your default browser. Pass --no-open to disable this behavior — useful in headless or CI environments.

Requirements

The explorer requires the @mimicai/explorer package. If it is not installed, the command will exit with an install hint:

bash

$ pnpm add @mimicai/explorer

mimic test

Run test scenarios against your AI agent, with optional auto-scenario generation from facts and export to eval platforms.

bash

$ mimic test [options]

Options:
  -S, --scenario <names...> Limit to specific scenarios
  -p, --persona <names...>  Limit to specific personas
  -f, --format <format>     Output format: cli, json, junit (default: cli)
  -o, --output <path>       Write report to file
  --ci                      CI mode: exit code 1 on failure
  -t, --timeout <ms>        Per-scenario timeout in ms
  --tier <tiers...>         Filter auto-generated scenarios by tier: smoke, functional, adversarial
  --export <format>         Export scenarios: mimic, promptfoo, braintrust, langsmith, inspect
  --inspect                 Shortcut for --export inspect
  --verbose                 Enable verbose logging
  --full                    Full pipeline: run → seed → serve → test → stop

Runs manual scenarios from mimic.json and, when auto_scenarios is enabled, generates additional scenarios from the fact manifest (.mimic/fact-manifest.json). The fact manifest is created automatically by mimic run. See Testing & Auto-Scenarios for the full guide.

Auto-scenario generation

When auto_scenarios: true is set in mimic.json (or when --tier or --export flags are used), Mimic reads the fact manifest and uses an LLM call to generate test scenarios from facts. Each fact becomes a scenario with natural-language input and specific assertions.

bash

# Generate + export to PromptFoo format
$ mimic test --export promptfoo

# Generate only smoke-tier scenarios
$ mimic test --tier smoke

# Export to Mimic's own JSON format
$ mimic test --export mimic

# Export to Inspect AI (Python task file)
$ mimic test --inspect

Export formats

Format	Output files	Description
`mimic`	`mimic-scenarios.json`	Mimic's native scenario format — paste into `mimic.json` or load standalone
`promptfoo`	`promptfooconfig.yaml`	PromptFoo config with contains/not-contains/javascript/llm-rubric assertions
`braintrust`	`braintrust-dataset.jsonl`, `braintrust-scorer.ts`	Braintrust dataset + TypeScript scorer
`langsmith`	`langsmith-dataset.json`, `langsmith-upload.ts`, `langsmith-evaluator.ts`	LangSmith dataset + upload script + evaluator
`inspect`	`inspect_task.py`	Self-contained Inspect AI Python task with dataset + scorer

All exports are written to .mimic/exports/.

mimic inspect

Show schema, data, or blueprint information.

bash

$ mimic inspect <subcommand>

inspect schema

Parse and display the database schema.

bash

$ mimic inspect schema [--verbose]

Shows tables, columns, primary/foreign keys, and enums. Use --verbose for per-table column details.

inspect data

Show row counts per persona per table.

bash

$ mimic inspect data [-p <names...>] [--verbose]

Displays a persona × table grid showing how many rows each persona generated.

inspect blueprints

List cached blueprints.

bash

$ mimic inspect blueprints [--verbose]

Shows a table with five columns for each cached blueprint in .mimic/blueprints/: persona ID slug, full name, occupation, the LLM model that generated it (Generated By), and the generation timestamp (Generated At).

inspect db

Query live database(s) for row/document counts.

bash

$ mimic inspect db [-d <name>] [--verbose]

Connects to your configured databases and reports current row counts. Use -d to inspect a specific database entry.

mimic clean

Truncate database tables and remove generated data.

bash

$ mimic clean [options]

Options:
  -y, --yes                Skip confirmation prompt
  --keep-blueprints        Keep cached blueprints in .mimic/blueprints/
  -d, --database <name>    Clean a specific database entry
  --verbose                Enable verbose logging

Truncates all Mimic-seeded tables in configured databases, removes .mimic/data/, and removes .mimic/blueprints/ (unless --keep-blueprints is set).

mimic adapters

Manage API mock adapters.

bash

$ mimic adapters <subcommand>

adapters add

Install an adapter package and add it to mimic.json.

bash

$ mimic adapters add <id> [--port <number>] [--no-install]

Installs the adapter npm package, adds an entry to the apis section in mimic.json, and shows available endpoints. Use --no-install to skip npm install and just update config.

adapters remove

Remove an adapter from mimic.json and uninstall the package.

bash

$ mimic adapters remove <id> [--no-uninstall]

adapters enable / disable

Toggle an adapter without removing it.

bash

$ mimic adapters enable <id>
$ mimic adapters disable <id>

Disabled adapters are skipped by mimic host.

adapters list

List all configured adapters with their status.

bash

$ mimic adapters list

Shows databases and API adapters, installation status, and enabled/disabled state.

adapters inspect

Show details and endpoints for an adapter.

bash

$ mimic adapters inspect <id>

Displays the adapter manifest (name, type, version, description) and lists all endpoints with their descriptions.

mimic info

Print environment and package info for bug reports.

bash

$ mimic info [options]

Options:
  --json                   Output as JSON

Prints system information (OS, architecture, Node version, package manager), installed @mimicai/* package versions, and whether a mimic.json config file is found in the current directory.

bash

$ mimic info

  Mimic Environment Info

  System:
    OS:              darwin (25.3.0)
    Arch:            arm64
    Node:            v22.14.0
    Package Manager: pnpm

  Packages:
    @mimicai/core              0.6.0
    @mimicai/cli               0.6.0
    @mimicai/adapter-stripe    0.6.0

  Config:
    mimic.json:      found

  Copy the above into your bug report.

Use --json for machine-readable output, useful in CI or automated diagnostics.

mimic init

mimic run

mimic seed

mimic host

What it starts

Port assignment

Transport

Connection summary

--no-api flag

Graceful shutdown

mimic explore

Background process

Port selection

Browser auto-open

Requirements

mimic test

Auto-scenario generation

Export formats

mimic inspect

inspect schema

inspect data

inspect blueprints

inspect db

mimic clean

mimic adapters

adapters add

adapters remove

adapters enable / disable

adapters list

adapters inspect

mimic info

`--no-api` flag