CLI & API

概要

Mimicry には mimicry CLI ツールが同梱されており、ターミナルや AI エージェントから通信ログの検索・モックルールの作成・プロキシのセットアップまで、GUI を一切操作せずに実行できます。核心にあるのは rule コマンドで、捕捉した実際のリクエストを起点に、エラーレスポンスへの差し替えやフィールド単位の書き換え、遅延の注入をワンコマンドで行えます。

インストール

brew tap kusumotoa/tap
brew install --cask mimicry

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

mimicry status

コマンド一覧

--json（1 行の JSON envelope で結果を返す。exit code 0〜7 と対応）はすべてのコマンドに共通です。--start-gui（GUI アプリが未起動なら自動起動して待つ）は、アプリを使うコマンドだけで有効で、単独で動くコマンドでは無視されます。

rule: エラー注入で動作確認する

典型的な流れは、対象リクエストを logs で捕捉し、その ID を起点にルールを作り、アプリを再操作して検証し、終わったら元に戻す、という 4 ステップです。コマンドが返った時点でルールは反映済みなので、sleep は不要です。

# 1. 対象リクエストの ID を確認する
mimicry logs --domain api.example.com --limit 5

# 2. そのログを起点に 500 エラーへ差し替える（実行時点で反映済み、sleep 不要）
mimicry rule set --from-log req-abc123 --status 500
# → Rule saved: rule-xyz789  GET  /api/orders/*  [full mock]

# 3. アプリを再操作してエラーハンドリングを検証する

# 4. 検証できたら元に戻す
mimicry rule delete rule-xyz789

フルモックへの差し替えだけでなく、実レスポンスを通しつつ 1 フィールドだけ書き換えることもできます。遅延の注入（--delay）はフルモックでもパススルー系（--patch / --merge / --against-real）でも使えます。遅延はリクエストが実サーバーへ到達する前に入るため、クライアントから見た待ち時間はどちらでも同じです。--ttl を付けたルールは、指定した時間が過ぎると、--times を付けたルールは、指定した回数だけ適用すると、アプリが自動で削除します。適用した回数は mimicry logs --json の ruleUse で確認できます。

# 実レスポンスは通しつつ、1 フィールドだけ書き換える
mimicry rule set --from-log req-abc123 --patch '/user/isPremium=true'

# フルモックに遅延を注入する
mimicry rule set --url '/api/heavy' --status 200 --body '{}' --delay 3000

# パススルーしつつ遅延だけ足す（--patch との併用も可能）
mimicry rule set --url '/api/heavy' --patch '/flag=true' --delay 3000

# 5 分で自動的に消える一時ルール
mimicry rule set --from-log req-abc123 --status 500 --ttl 5m

# 最初の 1 回だけ失敗させる（1 回適用したら自動で消える）
mimicry rule set --from-log req-abc123 --status 500 --times 1

project: 人間のルールを壊さない安全機能

rule set --id / rule delete / rule enable / rule disable は、対象ルールが --project で指定したプロジェクト（省略時は自動生成される「CLI Rules」のみ）の外にあると拒否されます。AI エージェントが GUI で人間が作った既存のモックルールを誤って書き換えたり削除したりしないための安全機能です。どんなプロジェクトが存在するかは project list で一覧できます。プロジェクトの作成・リネーム・複製・有効化/無効化と、その中のフォルダ操作（project folder ...）も CLI から行えますが、削除（delete）だけは取り消せない操作なので意図的に用意しておらず、GUI からのみ行えます。

# 存在するプロジェクトを確認する
mimicry project list

# "CLI Rules" の外にあるルールを操作するときは --project で明示する
mimicry rule delete rule-xyz789 --project "QA"

さらに、プロジェクト単位のロック機能もあります。新規作成したプロジェクトはデフォルトでロックされており、GUI サイドバーの鍵アイコン（または右クリックメニュー）から解除するまで CLI から読み取りも書き込みもできません。CLI 側にロック解除コマンドは意図的に用意していません — CLI 自身がロックを外せると安全機能の意味がなくなるためです。ロック中のプロジェクトへの操作は projectLocked エラー（exit 4）で拒否され、project list ではプロジェクトの存在と名前だけは見えますが、フォルダ・ルール件数の中身は伏せられます。

# ロック中のプロジェクトは存在は見えるが中身は伏せられる
mimicry project list --json
# → {"id": "...", "name": "QA", "locked": true, "ruleCount": 0, "folders": []}

# ロック中のプロジェクトを操作すると拒否される
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: 設定の書き出しと読み込み

rule export はプロジェクト・スクリプト・設定を JSON に書き出し、rule import がそのファイルを読み込みます。--out を付けなければ標準出力に出ます。

# バックアップを取る（権限 0600 で書き、既存のファイルは --force なしでは上書きしない）
mimicry rule export --out backup.json

# 読み込む（既定ではプロジェクトだけ。--scope で範囲を広げる）
mimicry rule import backup.json --scope projects,scripts

既定では、秘密になりうる値を伏せて書き出します。ヘッダー注入のヘッダー値と、保存リクエストのヘッダー・本文・URL のクエリが対象で、--reveal-secrets を付けたときだけ書き出されます。環境変数は名前と説明だけで、値は書き出されません。一方、モックルールの応答ヘッダー・本文とスクリプトのソースは、そのまま書き出されます。トークンや Cookie を直接書いていないか、書き出す前に確認してください。

読み込みでは、ヘッダー注入・スクリプト・保存リクエストのうち、同じ ID がすでにあるものはそのまま残します。プロジェクトは ID 単位で更新されます。OpenAPI の定義からルールを作るときは、rule import --openapi <path> を使います。

setup: プロキシとデバイスの準備

プロキシの起動、デバイス（シミュレータ/エミュレータ）へのプロキシ設定、CA 証明書のインストール（setup cert install）と macOS の CA の削除（setup cert delete）をまとめて扱います。setup status で何が揃っていて何が足りないかを確認するのが定石です。iOS シミュレータへの setup device は macOS のシステムプロキシを変更するため、Mac 上のすべてのアプリの通信が Mimicry を経由します（setup teardown で戻ります）。--target macos の証明書のインストールは、この Mac のログインキーチェーンに書き込み、キーチェーンを信頼するすべてのアプリに影響します。なお、プロキシを停止するコマンドは意図的に用意していません — AI エージェントが自分の通信の監視を止められないようにするためで、停止は GUI から行います。

# 何が揃っていて何が足りないかを確認する
mimicry setup status

# シミュレータにプロキシを設定する（CA 証明書は入らない）
mimicry setup device sim:0B4F1234-5678-90AB-CDEF-1234567890AB

# CA 証明書を入れる
mimicry setup cert install --target sim:0B4F1234-5678-90AB-CDEF-1234567890AB

# 作業が終わったら元に戻す
mimicry setup teardown

docs: 埋め込みドキュメントを読む

バイナリには 30 章の実用ドキュメントが埋め込まれており、アプリやプロキシを起動していない状態でも読めます。一覧は mimicry docs list で見られます。入口は cli/getting-started、ルールを差し替えて検証する流れは cli/rule-loop、--json の出力は cli/output-envelope、MCP は cli/mcp です。cli/output-contract は cli/output（出力まわりの章の索引）への別名で、正式名ではありません。

mimicry docs list
mimicry docs show cli/rule-loop

--json の出力と exit code

--json を付けると、標準出力に必ず 1 行の JSON が出ます。成功も失敗も同じ形（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"]}}

• 分岐には ok と error.kind を使い、message の文面には頼りません。ok: false になるのは exit code 2〜7 のときだけです。
• 失敗したら、まず error.next[0] を実行し、それで直らなければ error.docs の名前を mimicry docs show に渡して読みます。
• 警告は envelope の warnings[] にあり、標準エラー出力にも 1 件ずつ出ます。2 つの出力を混ぜて読むと JSON として解析できなくなるので、標準出力だけを読んでください。

その他の機能

このほかに、通信と画面録画を記録する mimicry recording（recording trim で録画の前後を切り詰められます。指定範囲にエントリが 1 件も残らない場合は拒否され、意図した操作なら --allow-empty を付けて再実行します。上書き前の内容は <id>.mimicry.bak として録画の隣に保存されます）、GUI なしでモックルールを配信する mimicry serve、モックルールと実サーバーの差分を検出する mimicry compare（既定では差分があっても exit 0 で、CI でゲートしたい場合は --fail-on-diff を付けると exit 1 になります）があります。

REST API

CLI と同じ機能を、ポート 19852 の REST API でも提供しています。AI エージェントや自動化スクリプトからは基本的に CLI を使うことを想定しているため、ここでは詳細は割愛します。API は 127.0.0.1 だけで待ち受け、Host / Origin ヘッダーを検証します。Mimicry Capture 用の 2 ルートを除くすべてのルートが、Authorization: Bearer <token> を要求します。トークンは起動のたびに生成され、~/Library/Application Support/com.mimicry.proxy/mimicry-token（権限 0600）に書かれます。CLI はこのファイルを自動で読みます。