CLI & API

Overview

Mimicry ships with the mimicry CLI tool, so a terminal or an AI agent can search traffic logs, author mock rules, and set up the proxy without ever touching the GUI. At its core is the rule command: starting from a captured request, you can swap in an error response, rewrite a single field, or inject a delay with one command.

Installation

brew tap kusumotoa/tap
brew install --cask mimicry

sudo ln -sf /Applications/Mimicry.app/Contents/MacOS/mimicry /usr/local/bin/mimicry

mimicry status

Command list

Every command shares --json (a single-line JSON envelope, whose exit code maps to 0-7) and --start-gui (auto-launch the GUI app and wait if it isn't running yet).

rule: verify behavior by injecting errors

The typical flow has four steps: capture the target request with logs, build a rule from its ID, re-operate the app to verify, then revert. The rule takes effect the moment the command returns, so there is no need to sleep.

# 1. Find the ID of the target request
mimicry logs --domain api.example.com --limit 5

# 2. Swap that request for a 500 error (takes effect immediately, no sleep needed)
mimicry rule set --from-log req-abc123 --status 500
# → Rule saved: rule-xyz789  GET  /api/orders/*  [full mock]

# 3. Re-operate the app to verify the error handling

# 4. Once verified, revert
mimicry rule delete rule-xyz789

Beyond swapping in a full mock, you can also let the real response through and rewrite just one field. A delay (--delay) works either way — on a full mock and on a passthrough rule (--patch / --merge / --against-real) alike. It fires before the request reaches the upstream, so the client-side latency is the same in both cases.

# Let the real response through and rewrite just one field
mimicry rule set --from-log req-abc123 --patch '/user/isPremium=true'

# Inject a delay into a full mock
mimicry rule set --url '/api/heavy' --status 200 --body '{}' --delay 3000

# Or add a delay to a passthrough rule (combining it with --patch is fine)
mimicry rule set --url '/api/heavy' --patch '/flag=true' --delay 3000

project: a safety net for humans' rules

rule set --id, rule delete, rule enable and rule disable are refused if the target rule sits outside the project named by --project (the auto-created "CLI Rules" project, if omitted). This keeps an AI agent from accidentally rewriting or deleting a mock rule a human authored in the GUI. Use project list to see which projects exist. Creating, renaming, duplicating, enabling and disabling projects — and managing the folders inside them (project folder ...) — are all available from the CLI too; only delete is deliberately missing, because it can't be undone, so it stays a GUI-only action.

# See what projects exist
mimicry project list

# Name the project explicitly to touch a rule outside "CLI Rules"
mimicry rule delete rule-xyz789 --project "QA"

There's also a per-project lock. A newly created project starts locked by default, and the CLI cannot read or write anything inside it until a human unlocks it from the lock icon in the GUI sidebar (or its right-click menu). There is deliberately no CLI command to unlock a project — letting the CLI unlock itself would defeat the point of the safety net. An operation on a locked project is refused with a projectLocked error (exit 4), and project list still shows a locked project's existence and name, but redacts its folders and rule count.

# A locked project's existence is visible, but its contents are redacted
mimicry project list --json
# → {"id": "...", "name": "QA", "locked": true, "ruleCount": 0, "folders": []}

# An operation on a locked project is refused
mimicry rule list --project "QA"
# → Error: this project is locked to CLI access — unlock it from the lock icon
#    next to the project in the Mimicry sidebar (or its right-click menu)

setup: get the proxy and device ready

Covers starting the proxy, pointing a device (iOS Simulator / Android) at it, and installing or removing the CA certificate (setup cert install / setup cert delete). Start with setup status to see what's ready and what's missing. There is deliberately no command to stop the proxy — that keeps an AI agent from disabling the monitoring of its own traffic; stop it from the GUI instead.

# See what's ready and what's missing
mimicry setup status

# Point an iOS Simulator / Android device at the proxy and install the CA cert
mimicry setup device sim:0B4F1234-5678-90AB-CDEF-1234567890AB

# Revert once you're done
mimicry setup teardown

docs: read the embedded documentation

Read the practical documentation embedded in the binary (cli/getting-started / cli/rule-loop / cli/setup / cli/devices / cli/recipes / cli/output-contract), even while the app and proxy are not running.

mimicry docs list
mimicry docs show cli/rule-loop

Other features

There's also mimicry recording to capture traffic plus screen recordings for later replay (recording trim cuts the head and tail off a recording; a range that would keep zero entries is refused, and you re-run it with --allow-empty if that really is what you meant. The pre-trim contents are kept next to the recording as <id>.mimicry.bak), mimicry serve to serve mock rules without the GUI, and mimicry compare to diff mock rules against a live server (a diff is exit 0 by default; add --fail-on-diff to get exit 1 for CI gating).

REST API

Mimicry exposes the same functionality as a REST API on port 19852. AI agents and automation scripts are expected to use the CLI in practice, so details are omitted here.