apiome mock
Global options such as --base-url, --tenant and --json go before the command — see CLI reference. Exit codes are listed in Exit codes.
apiome mock
Manage the hosted mock for published project versions.
apiome mock [OPTIONS] COMMAND [ARGS]...
Subcommands: config, disable, enable, preview, run, status, verify-attestation.
apiome mock config
Read, write and diff a version's mock configuration as one reviewable document.
apiome mock config [OPTIONS] COMMAND [ARGS]...
Subcommands: diff, pull, push.
apiome mock config diff
Show what pushing a mock configuration document would change (MSC-1.4).
Built for CI: exit 0 means the committed file and the version agree, exit 1 means they have drifted, and exit 2 means the check could not run at all (bad file, auth, network). That is the same split 'apiome diff' uses, for the same reason — a drift check that cannot tell "they differ" from "the server was down" is not a check.
apiome mock config diff [OPTIONS] PROJECT VERSION
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | yes | Project UUID or slug. |
VERSION | text | yes | Version UUID, slug, or label (e.g. 1.0.0). |
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--file, -f | path | yes | Mock configuration document (write one with 'apiome mock config pull'). |
apiome mock config pull
Write a version's whole mock configuration as one canonical document (MSC-1.4).
Correlation, scenarios, chaos and fixture packs, exactly as the control plane stores them, with keys sorted at every depth. The output depends only on the settings, so committing the file and pulling it again produces no diff — which is what lets 'apiome mock config diff' serve as a CI drift check.
The document carries no tenant, project or version, so the same file can be pushed to a staging version and then to a production one.
apiome mock config pull [OPTIONS] PROJECT VERSION
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | yes | Project UUID or slug. |
VERSION | text | yes | Version UUID, slug, or label (e.g. 1.0.0). |
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--out, -o | path | Write the document here instead of to stdout. |
apiome mock config push
Validate and apply a mock configuration document to a version (MSC-1.4).
The document replaces every section it carries — a section it omits is cleared, not left alone — so a committed file is the whole truth about what the mock returns.
Validation is the server's: the document is checked through the very routes that would store it, all of them, before any of them writes. A rejected document therefore leaves the version untouched and reports every problem at once, each against the path in the file that caused it. Exits 2 when the document is rejected.
apiome mock config push [OPTIONS] PROJECT VERSION
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | yes | Project UUID or slug. |
VERSION | text | yes | Version UUID, slug, or label (e.g. 1.0.0). |
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--file, -f | path | yes | Mock configuration document (write one with 'apiome mock config pull'). | |
--dry-run | flag | Validate the document and report what would change, without writing anything. |
apiome mock disable
Disable the hosted mock (PUT …/mock with enabled=false).
apiome mock disable [OPTIONS] PROJECT VERSION
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | yes | Project UUID or slug. |
VERSION | text | yes | Version UUID, slug, or label (e.g. 1.0.0). |
apiome mock enable
Enable the hosted mock (PUT …/mock; published versions only).
Draft versions are rejected by REST with a readable error and a non-zero exit code — the REST service is the authority on eligibility.
apiome mock enable [OPTIONS] PROJECT VERSION
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | yes | Project UUID or slug. |
VERSION | text | yes | Version UUID, slug, or label (e.g. 1.0.0). |
apiome mock preview
Render one request against a mock and print what it would return, and why (MSC-1.4).
Nothing is sent and nothing is written. The response carries the status, headers, media type and body the mock would serve, plus the decision trace naming which layer produced the body — a scenario and which rule, session-scoped CRUD, correlation and which pointers, or a declared example versus schema synthesis.
Two ways to reach the renderer, one answer either way, because both render through the portable runtime:
* PROJECT VERSION previews the hosted version through the MSC-1.2 dry-run endpoint. With
--file the render uses a local configuration document instead of the stored settings, so an
author can iterate before pushing.
* --bundle renders a portable mock bundle offline, launching the runtime the way 'mock run'
does. No API key, no tenant scope, no network.
Chaos is reported rather than applied: a preview that slept for a configured latency, or that randomly answered 500, would be answering a different question. The exit code reports whether the preview ran, not what the mock would answer — a previewed 404 exits 0.
apiome mock preview [OPTIONS] [PROJECT] [VERSION]
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | Project UUID or slug (omit with --bundle). | |
VERSION | text | Version UUID, slug, or label (omit with --bundle). |
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--method, -X | text | GET | HTTP method. | |
--path | text | / | Path relative to the version root (/pets/42); a ?query suffix is accepted. | |
--header, -H | text (repeatable) | Request header; repeatable. | ||
--query, -q | text (repeatable) | Query parameter; repeat a name for a multi-valued parameter. | ||
--body | text | Request body: a literal value, @FILE, or @- for stdin. Parsed as JSON when it is JSON. | ||
--scenario | text | Scenario to select (shorthand for the X-Mock-Scenario header). | ||
--seed | integer | Pin schema synthesis to this seed (shorthand for ?__seed=). | ||
--file, -f | path | Render against this local configuration document instead of the stored settings. | ||
--bundle | path | Render offline against a mock bundle, with no control-plane connection. | ||
--runtime | text | auto | With --bundle: auto (prefer a local apiome-mock), local, or docker. | |
--image | text | With --bundle --runtime docker: the container image (default: the official image). | ||
--require-signature | flag | With --bundle: refuse an unsigned bundle. |
apiome mock run
Run a portable mock bundle locally or in a container (PMR-1.2).
Talks to no control plane: the bundle is the whole configuration, so the same command works on a laptop, in CI, and inside an air-gapped network. The runtime launched here is the one the official image runs, so both answer the shared mock conformance corpus identically.
Set APIOME_MOCK_BUNDLE_SECRET to verify a signed bundle; the secret reaches the runtime through the environment and never appears on a command line.
apiome mock run [OPTIONS] BUNDLE
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
BUNDLE | path | yes | Mock bundle to serve (export one with the version mock bundle endpoint). |
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--host | text | 127.0.0.1 | Address to publish the mock on. | |
--port | integer range | 8775 | Port to publish the mock on. | |
--runtime | text | auto | Which runtime to launch: auto (prefer a local apiome-mock), local, or docker. | |
--image | text | Container image for --runtime docker (default: the official image). | ||
--base-path | text | version | Serve spec paths under /{tenant}/{project}/{version} (version) or at / (root). | |
--require-signature | flag | Refuse to start unless the bundle is signed. | ||
--log-level | text | Runtime log level (DEBUG, INFO, WARNING, ERROR, CRITICAL). | ||
--dry-run | flag | Print the command that would run, and exit. |
apiome mock status
Show mock state, base URL, and usage (GET …/versions/…, GET /v1/mocks/{tenant}/usage).
The usage summary is best-effort: when the usage endpoint is unavailable (mock server disabled or an older REST service) the status still prints without it.
apiome mock status [OPTIONS] PROJECT VERSION
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
PROJECT | text | yes | Project UUID or slug. |
VERSION | text | yes | Version UUID, slug, or label (e.g. 1.0.0). |
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--days | integer range | 30 | Usage rollup window in days (only used when the mock is enabled). |
apiome mock verify-attestation
Verify a release-proof mock attestation offline (PMR-3.2, no server round-trip).
Recomputes the DSSE PAEv1 HMAC-SHA256 signature with the shared secret and compares it against the envelope's signatures, then prints the four identities the attestation carries: the bundle digest it was served from, the runtime that served it, the conformance corpus and result, and the fixture packs.
Exits 0 only when the signature verifies and the attestation says the mock was verified — a signed statement that the mock failed, or was never verified, is a valid attestation and an unacceptable release proof, so the two are distinguished by the exit code rather than by prose.
apiome mock verify-attestation [OPTIONS]
Options
| Option | Type | Default | Required | Description |
|---|---|---|---|---|
--file, -f | path | yes | Attestation envelope JSON, as GET …/verification-runs/{id}/mock-attestation returns. | |
--secret, -s | text | yes | Shared HMAC secret (server: APIOME_LINT_ATTESTATION_SIGNING_SECRET). Env: APIOME_LINT_ATTESTATION_SECRET. |