Command line
The mock
| Command | What it does |
|---|
start [--port 8080] [--admin-port 8081] [--foreground] | Start the mock |
stop | Stop it |
status | Show the mode, the enabled packs and the active snapshot |
url [service] | Print the base URL to point a workflow at |
log [--service s] [--limit n] [--follow] | Show the requests the mock received |
up / down | Start or remove n8n and the mock together in Docker |
Packs
| Command | What it does |
|---|
packs list [--installed] | List shipped, installed and available packs |
packs enable <ids…> / packs disable <ids…> | Choose which services are mocked |
packs install <ids…> [--ref r] [--no-verify] | Download a pack that is not shipped in the package, checking each file's sha256 against the release index |
packs init <service> --domain <host> | Scaffold a pack to write by hand |
packs validate [service] [--json] | Check hand-written packs |
packs build <service> [--spec f] [--fetch] [--domains a,b] | Generate a pack from an OpenAPI file |
packs update [services…] | Refresh the cached OpenAPI files and rebuild what changed |
packs eject <service> [--force] | Copy a shipped pack into your project so you can edit it |
packs reset | Reset stored resources to their seed data |
packs audit | Download every source OpenAPI file and report on it |
Faults
| Command | What it does |
|---|
faults set <service> [--status n] [--delay ms] [--empty] [--after n] [--once] | Make calls to a service fail or slow down |
faults clear [service] | Remove faults |
Failure scenarios
| Command | What it does |
|---|
auth revoke <service> | Answer every call with the vendor's invalid-credential error |
auth forbid <service> | Answer every call with the vendor's missing-permission error |
auth clear [service] | Accept credentials again |
limits set <service> --calls n --per <duration> [--route '<METHOD> <path>'] | Allow n calls per window, then answer the vendor's rate-limit error until the window ends |
limits clear [service] | Remove rate limits |
Proxy mode and recording
| Command | What it does |
|---|
ca install [--host h] [--port n] | Print the environment variables that point n8n at the proxy |
on / off | Turn interception on (replay) or off |
record start / record stop | Record real traffic into a pack |
Your n8n instance
| Command | What it does |
|---|
instances add <name> <url> <apiKey> [--default] | Save an n8n instance and its API key |
instances use <name> / instances list | Pick the default instance, or list them |
snapshot <id|latest> [--workflow id] [--no-activate] [--commit] | Turn one execution into mocks and activate them |
diff [id] | Compare a later execution against the active snapshot |
creds push <type> [--name n] [--field k=v] [--dry-run] | Create a placeholder credential on the instance |
creds swap <workflow.json> [--in-place] [--real] [--via proxy] | Point a workflow's URLs at the mock, or back at the real service |
verify <service> --base-url u [--header h] [--param k=v] [--unsafe] [--patch] [--fail-on kinds] | Compare a pack against the real service. Exits 1 on a difference |
Fault injection
integration-mock faults set slack --status 503 --once
| Flag | Effect |
|---|
--status n | Answer with this HTTP status |
--delay ms | Wait before answering |
--empty | Answer with an empty body |
--after n | Let the first n calls through |
--once | Remove the fault after it fires |
Faulted calls are marked FAULT in the log.
Failure scenarios in detail
Switch on what a workflow meets when a credential stops working or a vendor rate-limits it:
integration-mock auth revoke slack
integration-mock limits set hubspot --calls 10 --per 10s --route 'POST /crm/v3/objects/contacts'
Each answer is the vendor's own, from the pack's scenarios block (see packs.md); a pack without one answers a generic 401, 403 or 429. A rate-limit answer always carries Retry-After.
| Option | Effect |
|---|
--calls n | Calls allowed per window (at least 1) |
--per <duration> | Window length: 500ms, 10s, 1m or 1h. The window opens at the first counted call |
--route '<METHOD> <path>' | Count and limit only this endpoint. The method may be *; the path uses pack-route syntax (:id matches one segment) |
Credentials are checked first, then limits, then faults. A rejected or limited call does not count against the limit, and does not use up a fault. auth revoke, auth forbid and limits set refuse a service that is not enabled. Scenarios, like faults, answer only while the mock is serving: in replay mode and in base-URL mode, not while it is off or recording. The log marks these answers AUTH and LIMIT; integration-mock status lists what is switched on. Scenarios last until cleared or the mock restarts; packs reset leaves them in place.
The request log
integration-mock log --limit 3
Each line has the time, method, service, path, status and the route that answered. A call that no route matched shows unmatched.
Admin API
start also opens the admin port (--admin-port, default 8081). The CLI drives the mock through it; other tools can too. On loopback it needs no token. Bound anywhere else (INTEGRATION_MOCK_ADMIN_BIND), it generates one at start, writes it to ~/.integration-mock/proxy.json, and requires it as a bearer token.
Two endpoints exist for tools that run a workflow themselves, such as workflow-tester:
| Endpoint | Does |
|---|
PUT /stores/<service> | Replaces that service's records for this session, body { "<collection>": [records] }. POST /packs/reset brings back the pack's own seed. 404 for a service no pack provides |
POST /serve | Answers one request, body { "method", "url", "headers"?, "body"? }, as if it had been intercepted: faults, scenarios, records and the request log apply. Reply { "status", "headers", "body" }. It never passes through: a URL no enabled pack claims gets a 501, logged as unmatched |
Where files live
| Path | Contents | Commit it? |
|---|
./.integration-mock/packs/ | Packs you wrote, recorded or ejected. A recorded pack's provenance says when it was recorded, by which release, and that it was redacted | Yes |
./.integration-mock/config.json | Which packs are enabled | No. It is gitignored |
./.integration-mock/snapshots/ | Snapshots | No, unless you pass --commit |
~/.integration-mock/config.json | Saved n8n instances and API keys, in plain text | |
~/.integration-mock/requests.jsonl | The request log, in plain text | |
~/.integration-mock/ca.pem, ca-key.pem | The local certificate authority for proxy mode. Created on first start | |
Set INTEGRATION_MOCK_HOME to move the ~/.integration-mock folder. Set INTEGRATION_MOCK_PACK_INDEX_URL to download packs from a mirror (<url>/<pack id>/<file>).