Sharing & Scaling

Mock as Code

Click a mock together in the dashboard and it lives only there. Mock as code means defining it in a file instead — checked into git, reviewed in a pull request, applied by a script or a CI job — so a mock's configuration has the same history and repeatability as the rest of your codebase.

Two pieces make this possible: a personal API key to authenticate outside the browser, and a small CLI that turns a JSON file into a POST/PATCH against the same management API the dashboard itself uses.

Personal API keys

Open Account → API keys and click Generate. The plaintext key is shown exactly once — copy it somewhere safe (a password manager, a CI secret store); if you lose it, revoke it and generate a new one.

A key authenticates like your browser session does, as a Bearer token:

Authorization: Bearer mbpat_...

It can do anything your account can do against the management API — create, edit, and delete any mock you own — so store it as a CI secret, never in a file that gets committed. Revoking a key from the Account page takes effect immediately.

Getting a config file

Two ways to get a mock's config as a file, no CLI or API key required:

  • Export → MockBase config, on any mock's page, downloads its current configuration as JSON.
  • New mock → Import config, from the dashboard, does the reverse: paste or upload that same JSON to create a fresh mock from it (with a newly assigned mock_id — it never overwrites the mock the file came from).

That round trip alone covers duplicating a mock, sharing one as a file, or checking a first version into git before you ever touch the CLI.

The CLI

mockbase-cli is a single dependency-free script (ships in the MockBase repository's cli/ directory) that reads a mock's configuration from a JSON file and pushes it, or pulls an existing mock down into one:

bash
export MOCKBASE_API_KEY=mbpat_...

node index.js push mocks/orders-api.json
# Created mock aBcD1234efGh. Wrote mock_id back into mocks/orders-api.json.

node index.js pull aBcD1234efGh mocks/orders-api.json

A config file looks like the payload you'd send to create a mock -- the same shape the dashboard's Export/Import config produce:

json
{
  "name": "Orders API",
  "routes": [
    {
      "method": "GET",
      "path": "/orders/{id}",
      "status_code": 200,
      "response_body": { "id": "{{ request.path_params.id }}", "status": "shipped" },
      "template_enabled": true
    }
  ]
}

The first push creates the mock and writes the assigned mock_id back into the file — commit that. Every push after that sees mock_id already there and updates the same mock instead of creating a new one, replacing routes, datasets, and the other fields below wholesale, the same as saving in the dashboard.

Fields a push actually sends (and what Export/Import config in the dashboard read too): name, routes, require_token, record_target_url, default_response, datasets. Anything else in a pulled or exported file (created_at, subdomain, token state, …) is server-assigned or a separate action neither the CLI nor the dashboard importer manages — it's written out for reference, and ignored on the way back in.

Prefer an AI agent over a script?

The same personal API key drives mockbase-mocks, a standalone MCP server that gives Claude Desktop, Claude Code, or any other MCP client direct tools to create, edit, inspect, and delete your mocks — no CLI or curl required, the agent just calls the tools. See MCP Server for setup and the full tool list.

Doing it yourself without the CLI

The CLI is a thin convenience layer — everything it does is two plain REST calls against the same management API endpoints:

bash
# Create (first time)
curl -X POST https://mockbase.org/api/v1/mocks \
  -H "Authorization: Bearer $MOCKBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @mocks/orders-api.json

# Update (once you have a mock_id)
curl -X PATCH https://mockbase.org/api/v1/mocks/$MOCK_ID \
  -H "Authorization: Bearer $MOCKBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @mocks/orders-api.json

If your CI environment can't run the script for some reason, or you're scripting from a language other than Node, these two calls are the whole contract.

Using it in CI

Nothing is published to the GitHub Actions marketplace yet, so a workflow just checks the script out and runs it directly:

yaml
name: Sync mocks
on:
  push:
    branches: [main]
    paths: ["mocks/**"]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: node cli/index.js push mocks/orders-api.json
        env:
          MOCKBASE_API_KEY: ${{ secrets.MOCKBASE_API_KEY }}
  • MCP Server — the same API key, wired up as tools for an AI agent instead of a script.
  • Import & Export via OpenAPI — a different route to the same goal: generate a mock's routes from a spec you already maintain, rather than hand-writing them.
  • Version History — every save (including one made by the CLI or the MCP server) is still snapshotted automatically, so a bad push is one restore away from undone.