Shimwire

One tool for both sides of an API you don't fully control yet: mock the parts that aren't built, and test the parts that are.

[](https://github.com/caspel26/shimwire/actions/workflows/ci.yml) [](LICENSE) [](https://bun.sh) [](https://www.typescriptlang.org/) [](#contributing)

shimwire reads an OpenAPI 3.x or Swagger 2.0 spec (older specs are converted automatically) and gives you two things from it, powered by one shared engine so they never drift apart:

• 🧪 Mock mode — a fake-but-schema-valid API server, so frontend work isn't blocked waiting on a backend.
• 🚀 Client mode — a scriptable, git-friendly HTTP test runner. Collections are version-controlled TOML files you can diff and review in a PR, not JSON blobs locked in a proprietary cloud tool.

---

Table of contents

• [✨ Features](#-features)
• [🤔 Why](#-why)
• [📦 Installation](#-installation)
• [🚀 Quick start](#-quick-start)
• [🧰 Commands](#-commands)
• [⚙️ Configuration](#️-configuration)
• [🖥️ Testing a frontend against the mock server](#️-testing-a-frontend-against-the-mock-server)
• [📄 Collection format](#-collection-format)
• [🩹 Errors & debugging](#-errors--debugging)
• [🏗️ Stack](#️-stack)
• [🤝 Contributing](#-contributing)
• [📜 License](#-license)

✨ Features

• 🔀 Spec-driven — mock server and test collections both come from the same OpenAPI/Swagger spec, so they can never disagree with each other.
• 📁 Git-native collections — plain TOML, reviewable in a normal PR diff, no proprietary cloud format.
• 🌐 CORS-ready mock server — on by default, so a browser frontend on another port just works.
• 📡 Live request log — watch your frontend's traffic hit the mock in real time.
• 🎭 Realistic fake data — schema-aware (respects type, format, enum, min/max), not just random junk.
• 🎯 Overrides — force a specific status, inject latency, or pin an exact response for edge-case testing.
• 🤖 Auto-scaffolding — generate builds a runnable collection from your spec, guessing request chaining and pre-filling auth.
• 🖱️ Interactive CLI — a guided menu (shimwire cli) for exploring a spec without memorizing flags.
• 📊 HTML reports — readable request/response detail for run, not just terminal noise.
• 🩺 Clean errors — one readable line and exit code 1 on failure, not a raw stack trace.

🤔 Why

Postman/Insomnia-style tools lock collections into proprietary formats that don't diff cleanly in git and don't run well in CI. Meanwhile, mocking a backend usually means hand-rolling fixtures that quietly drift from the real API contract. If you already have an OpenAPI (or Swagger 2.0) spec, both problems have the same fix: derive the mock and the test collection from that one source of truth — see [Features](#-features) above for what that gets you in practice.

📦 Installation

Requires Bun — shimwire runs directly off its #!/usr/bin/env bun shebang, no separate build/Node install needed.

npm install -g shimwire
# or, without installing anything:
bunx shimwire 

Prefer building from source (or want to contribute)?

git clone https://github.com/caspel26/shimwire
cd shimwire
bun install
bun run src/cli.ts 

Standalone binaries (no Bun install required to run) may come later.

🚀 Quick start

# scaffold a project
cd my-project/
shimwire init
# creates .shimwire/{collections,env,mock}/

# backend not ready yet? mock it from the OpenAPI/Swagger spec
shimwire mock openapi.yaml --port 4000
# GET  /users   → 200
# POST /users   → 201

# backend exists? auto-scaffold a runnable test collection from the same spec
shimwire generate --from openapi.yaml --out users.toml

# run it against a real backend
shimwire run users.toml --env dev
# ✓ create_user   POST /users        201  142ms
# ✓ get_user      GET  /users/42     200  38ms

# wire into CI
shimwire run smoke.toml --env staging --fail-on-error

# get a readable HTML report instead of squinting at terminal lines
shimwire run users.toml --env dev --report report.html

Prefer answering a few prompts instead of remembering flags? Try shimwire cli for a guided interactive menu.

Full transcript (text version of the recording above)

$ shimwire init
Created .shimwire/ in my-project
  .shimwire/collections/
  .shimwire/env/
  .shimwire/mock/
  .shimwire/config.toml (commented-out defaults for generate/run/mock)
  .gitignore (created — keeps .shimwire/env/*.toml out of git)

$ shimwire mock ./openapi.yaml --port 4100 --no-watch &
Loading spec from ./openapi.yaml...
Mock server running on http://localhost:4100
  GET    /pets  → 200
  POST   /pets  → 201
  GET    /pets/{id}  → 200

$ shimwire generate --from ./openapi.yaml --out .shimwire/collections/pets.toml
Loading OpenAPI spec from ./openapi.yaml...
Loaded "Petstore" — 2 path(s)
Generating collection...
Writing .shimwire/collections/pets.toml...
Wrote 3 request(s) to .shimwire/collections/pets.toml
1 item(s) flagged for manual review — see file header.

$ shimwire run .shimwire/collections/pets.toml --env dev
✓ list_pets       GET    /pets  200  7ms
✓ create_pet      POST   /pets  201  1ms
✓ get_pet         GET    /pets/44bf8c98-8527-4f60-b5d0-3b68dca9685a  200  0ms

$ shimwire run .shimwire/collections/pets.toml --env staging --fail-on-error
✗ list_pets       Unable to connect. Is the computer able to access the url?
✗ create_pet      Unable to connect. Is the computer able to access the url?
✗ get_pet         Unknown or not-yet-run step "steps.create_pet"

$ echo $?
1

That last block is the whole point: the same collection that runs clean against dev catches a broken staging environment, and the nonzero exit code is exactly what --fail-on-error is for in a CI job.

🧰 Commands

shimwire init

Scaffolds .shimwire/{collections,env,mock}/, a starter .shimwire/config.toml, and a .gitignore entry protecting .shimwire/env/*.toml secrets.

shimwire cli

Launches an interactive menu — pick "Mock", "Generate", "Workflow", "Run", or "Init" and answer a few validated prompts instead of remembering flags. Pre-fills answers from .shimwire/config.toml when present. Picking "Mock" starts the server in the background and returns to the menu, so you can immediately pick "Run" to test against it; after "Generate" it offers to run the collection it just wrote; "Workflow" lists every endpoint in a spec as a checkbox list to build a .shimwire/workflows/.toml without knowing ids up front. Useful when you're exploring a new spec rather than scripting something repeatable.

shimwire mock [spec]

Serves fake-but-schema-valid responses for every endpoint in a spec.

| Flag | Default | Description | | ------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------- | | [spec] | — | Path or URL to an OpenAPI 3.x / Swagger 2.0 spec. Falls back to [mock].spec in config. | | -p, --port | 4000 | Port to listen on. | | --overrides | .shimwire/mock/overrides.toml if present | Force specific status codes, bodies, or latency. | | -l, --allow-local | off | Allow fetching spec from localhost/private-network URLs (disables swagger-parser's SSRF guard). | | -k, --insecure | off | Skip TLS certificate verification while fetching spec (self-signed local certs). | | --cors / --no-cors | CORS on | Toggle permissive CORS headers. | | --watch / --no-watch | watch on | Toggle a live log line (time, method, path, status, duration) for every incoming request. |

shimwire generate

Auto-scaffolds a runnable collection from a spec, guessing request chaining and pre-filling auth.

| Flag | Default | Description | | ----------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | -f, --from | — | Path or URL to an OpenAPI 3.x / Swagger 2.0 spec. Falls back to [generate].from in config. | | -o, --out | — | Output path for the generated collection .toml. Falls back to [generate].out. | | -s, --security | first auto-configurable scheme | When a spec offers multiple auth alternatives, pin one by name. | | -l, --allow-local | off | Same SSRF-guard override as mock. | | -k, --insecure | off | Same TLS bypass as mock. |

If the spec has a login-shaped operation (by operationId/path, e.g. POST /auth/login) whose response has a token-shaped field, generate extracts it into .shimwire/workflows/authentication_flow.toml (see [Reusable workflows](#reusable-workflows)) instead of generating it as a top-level request, and every bearer-secured request gets depends_on = ["login"] with its token pointed at the login step's actual response field — instead of the static {{env.token}} guess. Always flagged for review: the login step's body has faked credentials, since real ones can't be guessed.

shimwire workflow

Hand-pick specific endpoints from a spec and save them as a reusable .shimwire/workflows/.toml — for building a workflow yourself rather than relying on generate's login auto-detection above, e.g. a multi-step flow that isn't just a single login call.

| Flag | Default | Description | | ----------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | -f, --from | — | Path or URL to an OpenAPI 3.x / Swagger 2.0 spec. Falls back to [generate].from in config. | | -n, --name | — | Workflow file to write, under .shimwire/workflows/. | | -e, --endpoints | — | Comma-separated request ids to include. | | -s, --security | first auto-configurable scheme | Same as generate. | | -l, --allow-local | off | Same SSRF-guard override as mock. | | -k, --insecure | off | Same TLS bypass as mock. |

shimwire workflow --from openapi.yaml --name authentication_flow --endpoints login

Don't know the ids offhand? shimwire cli → "Workflow" lists every operation in the spec as a checkbox list (method, path, and the id it'll get) instead of requiring --endpoints up front.

shimwire run

Runs a collection — or a standalone workflow — against a real backend.

| Flag | Default | Description | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | -e, --env | dev | Environment file under .shimwire/env/.toml. | | --only | — | Run a single request plus its dependencies. | | --fail-on-error | off | Exit non-zero if any request fails — for CI. | | -k, --insecure | off | Skip TLS certificate verification. | | -r, --report | — | Write an HTML report (full request/response detail, sensitive headers redacted). Falls back to [run].report in config. |

A workflow (.shimwire/workflows/.toml) can be run directly, the same as any collection — no need to wrap it in one just to try it out:

shimwire run .shimwire/workflows/authentication_flow.toml --env dev
# or, resolved the same way collection names are:
shimwire run authentication_flow.toml --env dev

run detects which shape a file is (a collection has [meta], a workflow doesn't) and, for a bare workflow, resolves {{env.base_url}} from --env exactly like a hand-written collection would.

shimwire mcp

Starts an MCP server (stdio transport) exposing shimwire's spec/collection/workflow tools to an AI client — Claude Desktop, Claude Code, or anything else that speaks MCP. Point a client's config at it:

{ "mcpServers": { "shimwire": { "command": "bunx", "args": ["shimwire", "mcp"] } } }

The recording below isn't a shimwire subcommand — it's [assets/mcp-demo-client.ts](assets/mcp-demo-client.ts), a small standalone script standing in for an AI agent, so you can see real tool calls and real responses instead of trusting a description:

| Tool | Does | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | load_spec | Parse a spec, list every operation's id/method/path — see what's actually available before generating anything. | | init_project | Scaffold .shimwire/. | | generate_collection | Same as shimwire generate — full collection from a spec, login auto-detected into a workflow. | | create_workflow | Same as shimwire workflow — hand-picked endpoints saved as a named workflow. | | list_collections / list_workflows | See what's already in the project. | | run_collection | Run a collection or workflow, get structured pass/fail back per step — so the result can be checked, not just assumed. | | start_mock | Start a mock server from a spec

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: caspel26
• Source: caspel26/shimwire
• License: MIT

Install and usage instructions live in the source repository linked above.