Use Mockphine CLI

Purpose

Run the same Mockphine workspace model from terminal instead of the desktop UI. The CLI reuses the same routing and matching rules, import and export flows, AI planner, and license gates.

What the CLI uses

• A workspace is one JSON file on disk.
• A workspace contains one or more servers, collections, endpoints, and same-route cases.
• run starts one foreground runtime for one selected server.
• status, stop, logs, and recording talk to that runtime over a localhost-only control plane.
• apply --plan is the bulk mutation path for scripts and AI agents.

Safe rules for Codex, Claude Code, Cursor, and other AI CLIs

If you use an external AI tool to work with Mockphine, let the AI plan the work but keep mockphine as the only mutation interface.

• Treat mockphine as the only write path.
• Never edit the workspace JSON file directly.
• Always pass an explicit --workspace.
• Prefer --json for reads and machine-checked verification.
• Read current state before mutating anything.
• Use route selectors like --server, --method, --path, --endpoint, and --case instead of parsing human-readable output.
• For larger changes, run apply --plan --dry-run before the real apply.
• Keep run in one terminal, then use status, stop, logs, or recording from a second terminal.

Install and verify

There are two practical ways to start using the CLI: use the bundled binary from a normal desktop install, or link a local development build from a source checkout.

Option 1: Use the bundled CLI from the desktop app

Current desktop installs already carry the CLI. You do not need a second package manager or a separate product to start using it.

macOS

/Applications/Mockphine.app/Contents/MacOS/mockphine-cli --version

If mockphine is not yet in your PATH, link it once first:

mkdir -p ~/.local/bin
ln -sf "/Applications/Mockphine.app/Contents/MacOS/mockphine-cli" ~/.local/bin/mockphine
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec zsh
mockphine --version

Windows

Add the Mockphine install root to PATH, open a new shell, then verify:

mockphine.exe --version

• Default per-user install root: %LocalAppData%\\Programs\\Mockphine
• macOS app bundles also include the man page and shell completions under /Applications/Mockphine.app/Contents/Resources/cli/.
• Custom MSI installs use your chosen install root instead.

Option 2: Link a local development build from a source checkout

If you are working inside the Mockphine repo, build the CLI once, link the debug binary into ~/.local/bin, add that folder to your shell PATH, then verify the command.

cargo build --manifest-path apps/desktop/src-tauri/Cargo.toml --bin mockphine
mkdir -p ~/.local/bin
ln -sf /path/to/mock-api-server/apps/desktop/src-tauri/target/debug/mockphine ~/.local/bin/mockphine
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec zsh
mockphine --version

• Replace /path/to/mock-api-server with your actual local checkout path.
• The example above uses zsh. If you use another shell, update the matching shell config file instead of ~/.zshrc.
• Re-run the cargo build step whenever you need a fresh local binary from new source changes.

Walkthrough: add payment endpoints from two terminals

This example uses the default macOS desktop workspace path and a server named payment. It shows how to inspect the existing server, add POST /payments and GET /charges/:id, run the server on a test port, and verify both responses. If your workspace path or server name differs, replace those values in the commands below.

Set the workspace path

export WS="$HOME/Library/Application Support/com.cuongnguyen.mockphine/workspace.json"

If mockphine is still not in your PATH, link it once first:

mkdir -p ~/.local/bin
ln -sf "/Applications/Mockphine.app/Contents/MacOS/mockphine-cli" ~/.local/bin/mockphine
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec zsh
mockphine --version

1. Check that the payment server already exists

mockphine --json server list --workspace "$WS"
mockphine --json endpoint list --workspace "$WS" --server payment

This shows the server and the routes already attached to it.

2. Add POST /payments

mockphine endpoint add --workspace "$WS" --server payment --method post --path /payments --mode mock

endpoint add creates the route itself, but not the full response yet.

3. Set the response for POST /payments

cat >/tmp/post-payments.json <<'EOF'
{
  "statusCode": 201,
  "body": "{\"created\":true,\"id\":\"pay_123\"}"
}
EOF

mockphine --json endpoint update \
  --workspace "$WS" \
  --server payment \
  --method post \
  --path /payments \
  --input /tmp/post-payments.json

This tells Mockphine what status code and body to return.

4. Add GET /charges/:id

mockphine endpoint add --workspace "$WS" --server payment --method get --path /charges/:id --mode mock

Here :id is a path parameter, so /charges/ch_123 matches this endpoint.

5. Set the response for GET /charges/:id

cat >/tmp/get-charge.json <<'EOF'
{
  "statusCode": 200,
  "body": "{\"charge\":\"sample\",\"status\":\"paid\"}"
}
EOF

mockphine --json endpoint update \
  --workspace "$WS" \
  --server payment \
  --method get \
  --path /charges/:id \
  --input /tmp/get-charge.json

6. Verify that both endpoints exist

mockphine --json endpoint list --workspace "$WS" --server payment
mockphine --json endpoint get --workspace "$WS" --server payment --method post --path /payments
mockphine --json endpoint get --workspace "$WS" --server payment --method get --path /charges/:id

7. Start the server on a test port

mockphine --json run --workspace "$WS" --server payment --port 38124

Keep that terminal open. run stays in the foreground.

8. Test from a second terminal

export WS="$HOME/Library/Application Support/com.cuongnguyen.mockphine/workspace.json"

curl -i -X POST http://127.0.0.1:38124/payments
curl -i http://127.0.0.1:38124/charges/ch_123
mockphine --json status --workspace "$WS" --server payment

• POST /payments returns 201 with {"created":true,"id":"pay_123"}.
• GET /charges/ch_123 returns 200 with {"charge":"sample","status":"paid"}.

9. Stop the server when you are done

mockphine --json stop --workspace "$WS" --server payment

Apply larger changes with plan files

Use direct endpoint commands when you are changing one or two routes. If you need to add several routes, create variants, or reshape a server in one pass, switch to apply --plan.

mockphine --json apply --workspace "$WS" --plan /tmp/mockphine-plan.json --dry-run
mockphine --json apply --workspace "$WS" --plan /tmp/mockphine-plan.json

• Use --dry-run first so you can inspect the mutation before it writes.
• apply --plan is usually the best default for external AI tools when the change is bigger than a couple of endpoints.

Use Mockphine AI commands from terminal

Mockphine also ships its own mockphine ai ... command family. Use it when you want help grounded in your workspace, want Mockphine to classify whether a prompt implies a mutation, or want to preview and apply a planner artifact from terminal.

mockphine --json ai chat --workspace "$WS" --prompt "How do I add GET /charges/:id?"
mockphine --json ai intent --workspace "$WS" --prompt "make GET /charges/:id return 503"
mockphine --json ai plan preview --workspace "$WS" --input /tmp/mockphine-ai-envelope.json --output /tmp/mockphine-ai-preview.json
mockphine --json ai plan apply --workspace "$WS" --preview /tmp/mockphine-ai-preview.json

• ai chat is for grounded help and explanation.
• ai intent tells you whether free-form text implies a mutation.
• ai plan preview writes a preview artifact, and ai plan apply applies that preview only if the workspace is still current.
• ai intent, ai plan preview, and ai plan apply require an activated license. Continue with Activate and license.
• If you prefer the desktop AI workflow, continue with AI Help Chat.

Built-in help and outputs

• Use --json when a script or AI agent needs deterministic machine-readable output.
• Use mockphine --help or mockphine help server for command help.
• Use mockphine docs cli and mockphine docs task-guide for task-oriented terminal docs.
• Use mockphine help --format man and mockphine completion zsh for man page and shell completions.

Command groups that matter first

• workspace: load, save, export, and import workspace snapshots.
• server, endpoint, case: author routes and same-route variants.
• logs and recording: inspect live traffic and create endpoints from captured requests.
• openapi, pack, scenario-pack, and server-folder: move mocks between teams, files, and repos.
• apply, settings, license, git, github, and ai: automate larger workflows once the basics are in place.

Know how routes match

• Routing starts with HTTP method plus normalized path, so /users and /users/ are treated as the same route.
• Query behavior is controlled by endpoint queryMode: NONE, EXACT, or CONTAINS.
• If no endpoint matches method, path, and query rules, and server fallback mode is STRICT, Mockphine returns 404 Not Mocked.

Common issues and fixes

• `mockphine` is not on your shell path: use the direct install path from this guide until you add a symlink or update PATH.
• `run` appears blocked: keep it open in one terminal and use a second shell for status, logs, or stop.
• `server is already running in another mockphine process`: check status, then stop the active runtime before you start another one.
• `address already in use`: run the server on another --port or free the existing process that already owns that port.
• `404 Not Mocked`: verify method, normalized path, and query rules with endpoint list, then confirm whether server fallback mode is STRICT or FALLBACK.
• `endpoint route ... was not found`: remember that endpoint update selects the route by its current method and path, not the route you want after mutation.
• `workspace changed since preview`: re-run ai plan preview because the preview artifact is stale.
• A command is entitlement-blocked: some CLI command families are license-gated. Continue with Activate and license.

Prefer the visual workflow instead? Continue withCreate a mock serverorImport and export.