hkuds--cli-anything/wiremock/agent-harness/WIREMOCK.md

WireMock CLI Harness — Standard Operating Procedure

What is WireMock?

WireMock is a flexible HTTP mock server used to stub and record HTTP interactions. It exposes a REST Admin API at /__admin/ for managing stubs, inspecting requests, controlling stateful scenarios, and recording traffic from real backends.

This CLI harness wraps those admin endpoints so agents and developers can control WireMock from the terminal or scripts without needing to craft raw HTTP calls.

---

Starting WireMock Standalone

Download

curl -fsSL https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/3.3.1/wiremock-standalone-3.3.1.jar \
     -o wiremock-standalone.jar

Start (default port 8080)

java -jar wiremock-standalone.jar --port 8080 --verbose

Start with persistent mappings directory

java -jar wiremock-standalone.jar \
  --port 8080 \
  --root-dir ./wiremock-data \
  --verbose

Start with HTTPS

java -jar wiremock-standalone.jar \
  --port 8443 \
  --https-port 8443 \
  --verbose

Docker (alternative)

docker run -d --name wiremock \
  -p 8080:8080 \
  wiremock/wiremock:latest

---

Installing the CLI

cd /path/to/agent-harness
pip install -e .
cli-anything-wiremock --help

---

Connection Configuration

All connection parameters can be set via environment variables or CLI flags.

Environment Variable	CLI Flag	Default	Description
WIREMOCK_HOST	--host	localhost	WireMock host
WIREMOCK_PORT	--port	8080	WireMock port
WIREMOCK_SCHEME	--scheme	http	http or https
WIREMOCK_USER	--user	(none)	Basic auth username
WIREMOCK_PASSWORD	--password	(none)	Basic auth password
WIREMOCK_JSON	--json	false	JSON output mode

Example — connect to a remote WireMock instance:

export WIREMOCK_HOST=wiremock.internal
export WIREMOCK_PORT=9090
cli-anything-wiremock status

---

Common Workflows

1. Verify the server is running

cli-anything-wiremock status

2. Create a simple stub

# Quick form: METHOD URL STATUS_CODE [--body JSON]
cli-anything-wiremock stub quick GET /api/users 200 --body '{"users":[]}'

# Full JSON form
cli-anything-wiremock stub create '{
  "request": { "method": "POST", "url": "/api/orders" },
  "response": { "status": 201, "body": "{\"id\":42}", "headers": { "Content-Type": "application/json" } }
}'

3. List all stubs

cli-anything-wiremock stub list
cli-anything-wiremock stub list --json   # machine-readable

4. Get a specific stub

cli-anything-wiremock stub get <stub-id>

5. Delete a stub

cli-anything-wiremock stub delete <stub-id>

6. Reset all stubs to defaults

cli-anything-wiremock stub reset

7. Persist stubs to disk

cli-anything-wiremock stub save

8. Import stubs from a file

cli-anything-wiremock stub import ./my-stubs.json

---

Request Verification

# List recent requests
cli-anything-wiremock request list
cli-anything-wiremock request list --limit 10

# Find requests matching a pattern
cli-anything-wiremock request find '{"method": "GET", "url": "/api/users"}'

# Count matching requests (useful for assertion)
cli-anything-wiremock request count '{"method": "POST", "urlPath": "/api/orders"}'

# List unmatched requests (404s)
cli-anything-wiremock request unmatched

# Clear the request journal
cli-anything-wiremock request reset

---

Stateful Scenario Testing

WireMock supports state machines (scenarios) to simulate multi-step workflows.

# List all scenarios and their current state
cli-anything-wiremock scenario list

# Set a specific scenario to a state
cli-anything-wiremock scenario set "login-flow" "logged-in"

# Reset all scenarios to initial state
cli-anything-wiremock scenario reset

---

Recording Traffic from a Real Backend

Use recording to auto-generate stubs from real API traffic.

# Start recording — proxy traffic to a real backend
cli-anything-wiremock record start https://api.example.com

# ... make requests to http://localhost:8080 — they are proxied and captured ...

# Stop recording and inspect captured stubs
cli-anything-wiremock record stop

# Check if currently recording
cli-anything-wiremock record status

# Take a snapshot of in-memory requests as stubs
cli-anything-wiremock record snapshot

---

Server Management

# Check WireMock version
cli-anything-wiremock settings version

# Get global settings
cli-anything-wiremock settings get

# Full reset (stubs + requests + scenarios)
cli-anything-wiremock reset

# Shutdown the server
cli-anything-wiremock shutdown

---

JSON Output Mode

All commands support --json for machine-readable output suitable for scripting or agent use:

cli-anything-wiremock --json stub list
cli-anything-wiremock --json request count '{"method":"GET","url":"/health"}'

JSON output varies by command type:

• Data commands return the raw WireMock API JSON directly (e.g. stub list returns {"mappings": [...], "total": N})
• Void operations (delete, reset, save) return {"status": "ok"}
• status command returns {"status": "running"|"stopped", "host": "...", "port": N}
• Errors return {"status": "error", "message": "..."} (printed to stderr in human mode)