CLI command reference

This is the full, organised list of mockarty-cli subcommands. The CLI
groups commands into four “categories” plus a small auth/state cluster.
Use this page when you know roughly what you want to do but don’t
remember the exact verb. For interactive help, run any command with
--help.

The categories are visible in mockarty-cli --help:

• Cat 1 — Utilities. Pure local helpers (free in every mode).
• Cat 2 — Install. Setup and lifecycle of the Mockarty installation.
• Cat 3 — Test runners. The licence-gated workhorses.
• Cat 4 — TUI. Interactive terminal UI.
• Auth & state. Login, config, namespace, tokens.

Most commands accept these global flags:

Layered LLM security

mockarty-cli llm-security manages the prompt-injection policy for the active
namespace. The active namespace comes from --namespace, the environment, or
the saved login context, in that order.

Add --installation to get, set, or events for the system-admin view.
See LLM Guardrails for policy examples and access rules.

mockarty-cli connections — immutable external connections

These commands use the configured server, token, and concrete namespace. Descriptor files contain exact secret references, never raw credentials. See Connection Authority.

Cat 1 — Utilities

Free in every mode. No server, no token required.

mockarty-cli ci — CI helpers

mockarty-cli generate — code generation

generate spec runs every other generator backwards: the input is always the
mocks the namespace already has, so it takes no file. The document goes to stdout
and the warnings — the mocks a specification cannot express — go to stderr, so
mockarty-cli generate spec --format openapi > openapi.json writes a file a
consumer can parse. Use --format asyncapi for Kafka/RabbitMQ/NATS/socket/SMTP
mocks, --tags/--folder to narrow the set, and --out to write to a file.

mockarty-cli serve — embedded mini-server

Boot a standalone mock server (HTTP, REST, gRPC) without talking to an
admin node. See Quick start for examples.

mockarty-cli mcp — stdio MCP server for AI agents

Run the CLI as a Model Context Protocol
server over stdio, so AI agents (Claude Code, Cursor, …) can drive Mockarty.
Add it to your MCP client config:

{
  "mcpServers": {
    "mockarty": {
      "command": "mockarty-cli",
      "args": ["mcp"]
    }
  }
}

Free local tools are always available — no server or token required:

When a server is configured (--server/--token, env vars, or a saved login
context), every MCP tool of that server is additionally proxied through
under its canonical name — those tools follow your license. If the server is
unreachable or the token is invalid, the CLI logs one warning to stderr and
continues with the local tools only. Pass --local-only to skip proxying.

mockarty-cli recorder — HAR recorder

Capture HTTP traffic via proxy. See Recorder for details.

mockarty-cli sniff — capture-to-HAR reverse proxy

Start a local reverse proxy that records all traffic into a HAR file —
point your application at it, then feed the HAR to mocking, testing or
fuzzing:

mockarty-cli sniff --target http://api.example.com --port 9090 --output traffic.har

mockarty-cli util — offline helpers

Free, air-gapped utilities that need no server and no license:

mockarty-cli tunnel — TCP / SSH tunnel

Forward local port(s) to a remote Mockarty server — direct TCP, or through
SSH for locked-down hosts (--ssh, key/agent/password auth).

mockarty-cli matcher — check HTTP matching

Use mockarty-cli matcher status with an administrator token when you need to
check how the server chooses a mock for incoming HTTP requests. It shows the
mode for each namespace (off, shadow, or on), the current revision, and
any differences found while comparing matching behavior. Review differences
before enabling the new matcher for a namespace. If the command says the
matcher is not initialized, ask the server administrator to check its setup.
This command only shows status; it does not change the mode.

mockarty-cli init — project scaffold

Generate a project skeleton in the current directory: a declarative
pipeline manifest (mockarty.yaml), ignore file and a sample collection.
Flavors: generic (default), python (pytest plugin), go (Go SDK test).

mockarty-cli extension — browser capture extension

Cat 2 — Install

Manage the local Mockarty installation.

Cat 3 — Test runners

The full feature surface. Licence-gated in Community / Licensed mode.

Mock authoring

mock serve --anon-limit N overrides the default 5-stub cap when the CLI
is in Anonymous mode. Useful for tests that need more stubs without a
server connection.

Functional test runner

Common flags:

• --reporter cli|json:file|junit:file|allure:dir|html:dir (repeatable).
• --namespace NS — override the active namespace.

Performance runner

Local CLI without a server: capped at 500 VU / 2 minutes (see
Feature gating).

Fuzzing

Subcommands match the server’s fuzz API; see mockarty-cli fuzz --help.

Postman / Newman compat

Recorder (server-side)

Contract testing

Chaos engineering (pre-GA — see Chaos pre-GA)

“opt-in” means: pass --i-know-this-is-preview or set
MOCKARTY_CHAOS_PREVIEW=1. Read-only commands work without opt-in.

Collections in git

Test flows (Go DSL)

Test plans & runs

Test case management (TCM)

Security agent

Secrets storage

AI prompts

UI & mobile tests

Recycle bin

Migration from other tools

--report <file> writes the migration preflight: which cases the destination cannot hold as written (no title, no steps, a priority outside its vocabulary, or the same external id twice in one run), credential-shaped fields found INSIDE the migrated data (named by case and field, never by value), and the exact external ids the run created — the list to delete if the migration was a mistake. Re-running is idempotent on those ids, so a partial migration is fixed by repeating it rather than by cleaning up first. The file is written 0600.
| migrate from-allure | Rewrite third-party Allure SDK imports onto Mockarty equivalents. |
| allure … | Drop-in allurectl replacement — ingest allure-results/ into TCM. |
| testit … | Upload JUnit XML (results upload --results/-r) or converted Test IT JSON (--file); manage Mockarty runs/configurations. Existing framework adapters still need replacement or conversion. |

Audit & search

Test reports

CI orchestration

Cat 4 — TUI

See TUI user guide for the full screen tour.

Auth & state

Config

Namespace

Token

Delegated credentials

Tokens whose namespace set, action set and expiry are frozen by the issuer and
cannot be widened by the holder. Use these for work shared with a contractor, a
CI job or an MCP client, instead of handing over an API token — whose namespace
is a default its holder can change. See
Delegated credentials.

create requires --namespaces and --expires. --namespaces is plural on
purpose: it is the SET the credential is frozen to, not the global --namespace
the CLI session works in.

# One namespace, read-only, 30 days.
mockarty-cli delegated-credential create --name ci-reader \
  --namespaces staging --actions read --expires 30d

# A holder uses it exactly as it would use an API token.
MOCKARTY_API_KEY=mkd_... mockarty-cli mock list

Store

Backup

Cluster (admin / support)

Agent knowledge review

For publication, --expires-at, --supersedes, and repeatable --contradicts
describe lifetime and relations. Preview relation targets in Missions → Knowledge
before using their IDs. Reuse the same idempotency key only when retrying the
same decision.

Exit codes

Every command returns 0 only when the work it was asked to do actually
succeeded. A command that reports a failure on screen never exits 0 — a CI
step can rely on the code alone.

Three codes carry a fixed meaning across the whole CLI, so a pipeline can
branch on them without knowing which command ran:

2 matters most in CI: it is the code that separates “your tests are red”
from “your pipeline step is misconfigured”. A mistyped subcommand
(mockarty-cli perf runn script.js) and an unknown flag both exit 2 — they
never look like a passing step.

mock convert --report preflight.json also writes what an import has to answer before anyone trusts it: which files were understood (and as which format), what was approximated (the gaps), which credentials the SOURCE artefacts carry — named by file, kind and JSON path, never by value — and what undoing the conversion means (the convert path writes files only, so it is a deletion, and the report says exactly which directory). The file is written 0600: it is a map of where credentials live.
| results upload | every result in the bundle was stored on the server | 1 — the directory held no result, or the server stored only part of the bundle (the count says how many of how many); 2 — no server configured, or the server does not accept result uploads (nothing was stored). Use --dry-run when you only want the local summary. |
| allure upload | every *-result.json and referenced attachment reached Mockarty | 1 — any result or attachment failed to upload, an upload was interrupted, or the directory held no results |
| allure export | at least one *-result.json was written, plus the sidecars | 1 — the run carried no result, a --filter-by-* excluded every result, a sidecar could not be written, or (with --plan-id) any run in the suite failed to export |
| allure launch create | the launch exists and LAUNCH_ID= was printed | 2 — the server answered without a launch id, so nothing can be attached to the launch |
| allure launch close | the launch closed and its recorded outcome is green | 1 — the launch closed as failed, or it received no results at all. --abort records an aborted pipeline and keeps its own verdict. |
| testit results upload | every parsed result reached Mockarty | 1 — empty or malformed input, or any result did not reach the server (the count says how many of how many) |
| testit import | the export was ingested (cases created or updated) | 1 — a work item failed, or nothing at all was imported; 2 — the server’s summary could not be read, so the import cannot be confirmed |
| collection export-git | the tree was written to --dir | 1 — the server returned an empty archive (no file was written) |
| collection import-git | every request in the tree was imported | 1 — any request failed (HTTP 207 partial import) or none was imported; 2 — the server’s summary could not be read |
| recorder import-ui-actions | every parsed action was accepted by the session | 1 — no UI action was recognised in the file (wrong dialect), or the session kept fewer actions than were sent. --dry-run fails on the same empty-parse condition. |
| mobile run | the run was dispatched (and, with --wait, passed) | 1 — the run failed, or a device in --all-devices / --device-selector could not be dispatched to; 2 — the server accepted the run without returning a task id, so it cannot be tracked |
| mobile apps upload | the build was stored and its id printed | 2 — the server returned no artifact id, so nothing can reference the build |
| chaos cluster test | connected AND the capability probe completed | 1 — the capability probe failed; the cluster is not confirmed usable for experiments |
| chaos cluster info | every section of the report was read | 1 — a section (namespaces, nodes, capabilities) could not be read |
| chaos operator install | RBAC and the deployment were created | 1 — a prerequisite (ServiceAccount, ClusterRole, binding) could not be created; the operator is not deployed |
| chaos operator status | the operator is deployed and ready | 1 — not installed, or fewer replicas ready than desired |
| chaos operator uninstall | every object was removed | 1 — an object is still on the cluster (a leftover ClusterRole keeps cluster-wide permissions bound) |
| health | the server answered and reports itself healthy | 1 — the server is unreachable or reports a non-healthy status |
| verify | every requested check passed | 1 — a check failed; 2 — no server configured |
| testplan run --wait | the run finished with no failed item | 1 failed · 2 cancelled · 3 wait timed out |

Five of these deserve a note because they are easy to get wrong in a pipeline:

• A run that executes nothing is a failure, not a pass. --folder matches a
  request-name prefix, not a folder path, so a filter that matches nothing
  is a common way to end up testing nothing. The same applies to a test run
  manifest where a dependsOn typo skips every step.
• A load test that measures nothing is a failure. If the summary shows
  Requests: 0, look at the ERROR: lines above it — an iteration that throws
  (a missing import http from "k6/http", for example) leaves nothing to
  measure.
• A report you asked for and did not get is a failure. If
  --reporter junit:report.xml cannot write the file, the command fails even
  when every test passed — otherwise CI collects an artefact that does not
  exist.
• An upload or export that delivered nothing is a failure. allure upload,
  testit results upload and results upload fail on an empty results
  directory, and fail again when the server stores only part of what was sent —
  a run history missing rows is worse than one that never claimed to exist.
  allure export fails when it writes no *-result.json, because allure generate cannot build a report from the empty directory it just produced.
• -o json never changes the verdict. The machine-readable output of a
  contract gate carries the same exit code as the human-readable one.

Autonomous-mission retention

mockarty-cli autonomy settings get reads the current namespace policy. autonomy settings set changes the autonomous run wall with --run-window-minutes, or clears that override with --inherit-run-window. The same command changes --event-days / --payload-days, or clears them with --inherit-event / --inherit-payload. Use --request-id <stable-id> and reuse that value after a timeout or lost response; a new invocation without the flag intentionally starts a new mutation receipt.

Delivery-policy environments

These commands require an administrator credential and a configured authority
connection. Request JSON contains id (create only), projectId, class,
profile, auditId, and evidenceId; it must not contain approval seals.

mockarty-cli delivery-policy environments list --status active --limit 50
mockarty-cli delivery-policy environments get staging
mockarty-cli delivery-policy environments create --file environment.json --idempotency-key staging-v1
mockarty-cli delivery-policy environments advance staging --file environment-v2.json --etag '"dp-env:..."' --idempotency-key staging-v2
mockarty-cli delivery-policy environments revoke staging --etag '"dp-env:..."'
mockarty-cli delivery-policy grants get grant-123

Completion scripts

mockarty-cli completion bash > /etc/bash_completion.d/mockarty-cli
mockarty-cli completion zsh  > "${fpath[1]}/_mockarty-cli"
mockarty-cli completion fish > ~/.config/fish/completions/mockarty-cli.fish
mockarty-cli completion powershell | Out-String | Invoke-Expression

Where to next

• CLI user guide — narrative walkthrough.
• TUI user guide — interactive surface.
• OAuth login walkthrough — authentication details.
• Feature gating — what each mode unlocks.
• Chaos pre-GA — opt-in mechanism.
• Allure annotations — rich reporting.