CLI

Command reference for mockingpug's CLI. Every command operates on process.cwd(): there's no --dir <path> flag; run it from your project root, same as npm or git.

npm install -D mockingpug
npx mpug <command>

The binary is also registered as mockingpug (npx mockingpug <command>), kept as an alternative for anyone who prefers the full name.

Every example on this page uses npx mpug <command>; substitute your package manager's own one-off-execute command if you're not on npm — same <command>/flags either way, verified in CI against every manager listed:

pnpm dlx/yarn dlx/plain npx without a prior install all fetch fresh from the registry each time rather than using a project-local install — fine for a quick one-off doctor check, but slower and not what you want in a script that runs on every dev/build; install as a dev dependency first for those.

init

npx mpug init

Scaffolds mock.config.js, mock/api/, and mock/data/ in the current directory. Idempotent and non-destructive:

• If mock.config.js already exists, it prints already exists, nothing to do and stops. It never overwrites your config.
• An example schema (mock/api/example/schema.json) is only added if mock/api/ is completely empty, so running init in a project that already has real schemas doesn't clutter it.

init also detects your package manager from its lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb/bun.lock, deno.lock/deno.json/ deno.jsonc; falls back to npm if none exist yet) and prints the "next steps" in that manager's own run syntax — pnpm exec mpug doctor instead of npx mpug doctor, and so on for each of the five managers listed above.

doctor

npx mpug doctor
npx mpug doctor --strict
npx mpug doctor --assert-prod-safe <build-output-dir>

Validates every schema under mock/api/** without touching the store: unknown generator types (with a "did you mean" suggestion on typos), missing/malformed amount/data, broken data.* cross-entity references, and unresolvable dependency cycles. If persist.adapter: 'file', it also checks for orphaned entities: data left in .mockingpug/db whose schema no longer exists. It also warns when an entity's amount or an array[type].N exceeds limits.maxAmount/limits.maxArrayDepth, a DoS-guard as much as a perf one, and warns about any literal record that's missing a schema field or has the wrong type for one (literal bypasses generation entirely, so it's never structurally checked the way generated records are).

• Exit code 0 if everything's valid (orphans and limit overruns are only warnings, not failures, by default).
• --strict promotes those warnings to a hard failure (exit code 1), meant for CI, so a schema silently removed without pruning its old data (or one that quietly grew past a sane amount) doesn't slip through.
• --assert-prod-safe <dir> greps a production build output directory (e.g. your Next.js .next or Vite dist) for markers that mean the mock layer leaked into it: mockServiceWorker.js, or a bundled reference to mockingpug/dist/react/mockingpug/dist/next. Always a hard failure regardless of --strict, meant as a CI gate right after your production build step. Best-effort: it's a static grep, not a guarantee against a minified bundle hiding the reference.

generate

npx mpug generate

Loads your schemas and reconciles them into the configured store (persist.adapter: 'file' → .mockingpug/db/*.json, 'memory' → nothing persists past this process). See Reconciliation & Storage for exactly what "reconciles" means when a schema changed since the last run.

Exit code 1 on a schema error (invalid JSON, unknown type, broken reference, etc.). The message includes a stable error code (e.g. MP-SCHEMA-007) and which file/field is at fault.

Useful in CI for deterministic fixtures: mpug generate produces the exact same dataset every time, given the same seed and schemas.

reset

npx mpug reset --yes

Wipes the store entirely: destructive and irreversible, including any manual mutations made while testing (POST/PUT/DELETE against a running app). Refuses to run without --yes.

prune

npx mpug prune          # lists what would be deleted
npx mpug prune --yes    # actually deletes it

Deletes only orphaned entities (schema removed from mock/api, data still sitting in the store), leaving everything else untouched. Also refuses without --yes; without it, it lists which entities it found and exits 1.

types

npx mpug types

Writes .mockingpug/types/index.d.ts: one export interface per entity, mirroring its schema's data block (crossRef fields resolve to the target entity's type or field type, custom dictionaries with all-primitive values become a literal union, e.g. role: "ADMIN" | "USER" | "MODER"). Regenerate it any time after changing mock/api/**. There's no watch mode, this is a one-shot codegen step.

docs

npx mpug docs

Writes an API reference describing the REST surface every entity's mock exposes — GET/POST on the collection, GET/PUT/PATCH/DELETE on one record, every query parameter (pagination, sort, q/searchFields, one optional filter param per schema field), and the response envelope shape from mock.config.js's pagination config:

• .mockingpug/docs/openapi.json: a standard OpenAPI 3.1 document, importable into a real Swagger UI/Postman/Redocly.
• .mockingpug/docs/index.html: a dependency-free static page rendering the same spec (no swagger-ui-dist/Redoc pulled in), openable straight off disk with no server needed.

The devtools sub-API ({baseUrl}/__mockingpug/*) isn't part of this output — it's an internal channel, not part of the contract being mocked. Same one-shot model as types: regenerate after changing mock/api/**.

generators

npx mpug generators

Prints every DSL form the parser recognizes — uuid, number/number.<min>-<max>/ number.float.<min>-<max>.<precision>/number.increment, username.FS/.NN, email, hash, lorem, date, boolean, enum[...], array[...].<count>, slugify[...], custom dictionaries, conditionals, and data.<entity> relations — grouped by category, each with a one-line description and a runnable example where the form fits in a single string. It's generated straight from the same catalog a test pipes through the real parser, so it can't drift out of sync with what a given release actually accepts, unlike this page. Doesn't touch mock.config.js or the filesystem, so it works from any directory, without a project scaffolded yet.

migrate

npx mpug migrate        # dry-run: prints the plan, writes nothing
npx mpug migrate --yes  # apply

Converts a legacy project — one mock/api/<entity>/schema.json per entity, where each file was both a table and its implicit REST — into the current split format:

• mock/tables/<entity>.json — the data only (amount, data, fixtures?, literal?); a table-level bypass is dropped here (it moves onto the endpoints);
• mock/routes/<entity>.json — the six endpoints that reproduce the old CRUD: GET /<e> (list), GET /<e>/:id (one), and POST/PUT/PATCH/ DELETE as mutation (a method map — responds 200, doesn't change stored data; real writes are action, coming later). A table bypass is copied onto every generated endpoint.

Then it removes the migrated mock/api/ folders. It never overwrites an existing tables/<e>.json or routes/<e>.json (those entities are skipped with a warning), so re-running is safe. Default is a dry-run; pass --yes to actually write and delete.

Cloud sync: login, link, pull

Optional. mockingpug works fully offline from local JSON — cloud sync is for teams who author schemas in MockingPug Cloud and mirror them into the repo. The cloud owns the schema; a local checkout is a mirror of it, plus any local-only code (custom generators, handlers/).

login

npx mpug login

Device auth: opens the browser, you approve, and the token (mp_cli_…) is written to your user config (~/.config/mockingpug/auth.json), never the repo. In CI, set MOCKINGPUG_TOKEN (mp_ci_…) instead — it takes priority over the config file.

link

npx mpug link <projectId>            # e.g. proj_abc123
npx mpug link <projectId> --no-push  # link only, don't upload local mocks

Ties this folder to a cloud project (writes .mockingpug/project.json — commit it). What it does next depends on whether you already have local mocks:

• No local mocks → immediately pulls the published version down (a fresh mirror). Nothing published yet → it just links.
• Local mocks present → pushes them into the project's draft (the cloud merges: your local wins per name/id, unmatched cloud entries stay). Nothing is published and nothing is pulled — open the cloud editor, review the draft, Publish, then pull. --no-push skips the upload (link only; mirror later with pull --yes).

Push needs a personal token with edit schema rights; a CI token (MOCKINGPUG_TOKEN) is read-only and will get a clear CLOUD-FORBIDDEN. If someone has the cloud editor open, push is refused with CLOUD-BUSY (close it and retry).

pull

npx mpug pull                    # mirror the latest published version
npx mpug pull --yes              # don't prompt before overwriting/removing
npx mpug pull --watch            # keep syncing as cloud publishes new versions
npx mpug pull --version 12       # pin a published version (CI)
npx mpug pull --project proj_x   # target a project without a link file (CI)
npx mpug pull --force            # mirror even if a local push is unpublished

A 1:1 mirror of the published version. In mock/tables/, mock/routes/ and mock/data/ it writes what cloud has and removes local files cloud no longer has (a locally-added table or endpoint disappears on the next pull), and it clears out any legacy mock/api/. Everything else is out of scope and never touched: mock/handlers/, your custom generator code, and mock.config.js (a differing seed is only warned about).

Because it can delete and overwrite, pull shows the plan and refuses without --yes when it would overwrite a locally-changed file or remove one.

If you ran link/push and haven't Published the draft yet, pull holds off (writes nothing) so it won't roll your local source back to the older published version — Publish it in the editor first, or pass --force to mirror the published version and discard the draft. --watch waits for the Publish and then mirrors automatically.

Logs and errors

Every message is prefixed [mockingpug]; warnings are prefixed [mockingpug] warning:. Errors carry a stable code (see Reference → Error Codes) and, where relevant, the exact file/field at fault plus a fix suggestion. Anything that reaches the CLI without one of these codes is treated as a genuine bug in mockingpug itself, not a project misconfiguration: it prints with its full stack trace (unexpected internal error:) instead of a clean one-liner, on purpose.

Full config reference

See Reference → mock.config.js for every field this file accepts.