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:
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.jsonA config file looks like the payload you'd send to create a mock -- the same shape the dashboard's Export/Import config produce:
{
"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:
# 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.jsonIf 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:
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 }}Related
- 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.