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

--json (a single-line JSON envelope, whose exit code maps to 0-7) is common to every command. --start-gui (auto-launch the GUI app and wait if it isn't running yet) takes effect only on commands that use the app, and is ignored by the standalone ones.

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. The app deletes a rule with --ttl once the given time has passed, and a rule with --times once it has been applied that many times. You can see how many times it has been applied in ruleUse of mimicry logs --json.

# 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

# A temporary rule that deletes itself after 5 minutes
mimicry rule set --from-log req-abc123 --status 500 --ttl 5m

# Fail only the first request (the rule deletes itself after one use)
mimicry rule set --from-log req-abc123 --status 500 --times 1

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)

rule export / import: writing and reading settings

rule export writes projects, scripts, and settings to JSON, and rule import reads that file back. Without --out, it goes to standard output.

# Take a backup (written with mode 0600; an existing file is not overwritten without --force)
mimicry rule export --out backup.json

# Read it back (projects only by default; widen it with --scope)
mimicry rule import backup.json --scope projects,scripts

By default, values that may be secrets are left out of the export: the header values of header injections, and the headers, bodies and URL query strings of saved requests. They are written only with --reveal-secrets. Environment variables are written by name and description only, never their values. On the other hand, mock rules' response headers and bodies, and script sources, are written as they are, so check that you have not typed a token or cookie into them before exporting.

An import keeps what is already there: a header injection, script or saved request whose ID already exists is left as it is, and projects are updated by ID. To create rules from an OpenAPI definition, use rule import --openapi <path>.

setup: get the proxy and device ready

Covers starting the proxy, pointing a device (iOS Simulator / Android) at it, installing the CA certificate (setup cert install), and removing the macOS one (setup cert delete). Start with setup status to see what's ready and what's missing. setup device for an iOS Simulator changes the macOS system proxy, so traffic from every app on this Mac goes through Mimicry (setup teardown reverts it). Installing the certificate with --target macos writes to this Mac's login keychain and affects every app that trusts the keychain. 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 the simulator at the proxy (this does not install the CA)
mimicry setup device sim:0B4F1234-5678-90AB-CDEF-1234567890AB

# Install the CA certificate
mimicry setup cert install --target sim:0B4F1234-5678-90AB-CDEF-1234567890AB

# Revert once you're done
mimicry setup teardown

docs: read the embedded documentation

The binary embeds 30 chapters of practical documentation, which you can read even while the app and proxy are not running. mimicry docs list shows them all. Start from cli/getting-started; cli/rule-loop covers swapping rules and verifying, cli/output-envelope covers the --json output, and cli/mcp covers MCP. cli/output-contract is an alias for cli/output (the index of the output chapters), not a canonical name.

mimicry docs list
mimicry docs show cli/rule-loop

--json output and exit codes

With --json, standard output is always exactly one line of JSON. Success and failure share the same shape (the envelope).

{"ok":true,"schema":1,"command":"rule.set","exitCode":0,"data":{...},"warnings":[{"kind":"...","message":"...","next":["..."]}]}
{"ok":false,"schema":1,"command":"rule.set","exitCode":4,"error":{"kind":"guiNotRunning","message":"...","detail":{},"docs":"cli/getting-started","next":["mimicry status --start-gui"]}}

• Branch on ok and error.kind, not on the wording of message. ok: false happens only for exit codes 2-7.
• On a failure, run error.next[0] first; if that does not fix it, pass the name in error.docs to mimicry docs show and read it.
• Warnings are in the envelope's warnings[] and are also printed to standard error, one per line. Reading both streams together breaks the JSON parse, so read standard output on its own.

Other features

There's also mimicry recording to capture traffic plus screen recordings (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. The API listens on 127.0.0.1 only and validates the Host / Origin headers. Every route except the two used by Mimicry Capture requires Authorization: Bearer <token>. The token is generated on every launch and written to ~/Library/Application Support/com.mimicry.proxy/mimicry-token (mode 0600), and the CLI reads that file automatically.