Mockarty CLI

Mockarty CLI is a powerful command-line tool for API mocking, testing, fuzzing, performance testing, and CI/CD integration. It works in standalone mode (free, no server required) and connected mode (with a Mockarty server for full platform features).

Zero dependencies. Single binary. Works offline. 5 report formats.

About URLs in examples: All examples use localhost:5770 as the default Mockarty address. If your instance runs on a remote server, replace localhost:5770 with its actual address (e.g. https://mockarty.company.com or http://192.168.1.50:5770). See Tips & Useful Features for details.

Installation

macOS / Linux

curl -sSL https://mockarty.ru/install.sh | sh

Homebrew

brew install mockarty/tap/mockarty-cli

Go

go install github.com/mockarty/mockarty-cli@latest

Docker

docker run --rm mockarty/cli version

Verify the installation:

mockarty-cli version

Quick Start

1. Start a standalone mock server

echo '{"id":"hello","http":{"route":"/hello/:name","httpMethod":"GET"},
  "response":{"statusCode":200,"payload":{"message":"Hello, $.pathParam.name!","uuid":"$.fake.UUID"}}}' > mock.json

mockarty-cli serve -f mock.json --port 8080
curl http://localhost:8080/hello/World
# {"message":"Hello, World!","uuid":"a1b2c3d4-..."}

2. Run an API test collection

mockarty-cli run -f collection.json --reporter cli --reporter html:report.html

3. Create a mock on a connected server

mockarty-cli login --server https://mockarty.company.com --token mk_xxx
mockarty-cli mock create -f mock.json

Configuration

Setting the Server URL

By default mockarty-cli points at the managed Mockarty cloud (https://cloud.mockarty.com). You can target any other server — a local make rebuild instance, a self-hosted node, or an air-gapped deployment — through any of four mechanisms. Higher rows win.

The legacy MOCKARTY_SERVER_URL env var is still accepted as a synonym for MOCKARTY_SERVER to keep old CI scripts working. If both are set, MOCKARTY_SERVER wins.

See Connect to a Server for a deeper walkthrough.

Authentication

# OAuth (recommended; uses the current server URL — cloud by default)
mockarty-cli auth login

# API token (CI/CD, scripts)
mockarty-cli login --server https://mockarty.company.com --token mk_xxx

# Username/password (interactive)
mockarty-cli login --server https://mockarty.company.com --user admin --password secret

# Name the context explicitly
mockarty-cli login --server https://mockarty.company.com --token mk_xxx --name production

# Check current status
mockarty-cli login --status

Environment variables (override config, ideal for CI/CD):

Config file location: ~/.mockarty/config.json

Contexts

Contexts let you manage multiple server connections (like kubectl contexts):

# View all contexts
mockarty-cli config view

# List contexts as table
mockarty-cli config get-contexts

# Switch context
mockarty-cli config use-context production

# Create/update context manually
mockarty-cli config set-context staging --server https://staging.company.com --token mk_xxx --namespace test

# Delete context
mockarty-cli config delete-context old-server

Commands Reference

Mock Server (serve) – Standalone

Start a local mock server with the full Mockarty resolver engine. No server required.

mockarty-cli serve -f mocks/                              # From directory
mockarty-cli serve -f mock.json --port 9090               # Single file, custom port
mockarty-cli serve --har traffic.har                      # From HAR recording
mockarty-cli serve -f mocks/ --proto protos/ --grpc-port 50051  # With gRPC
mockarty-cli serve -f mocks/ --watch                      # Hot-reload on changes
mockarty-cli serve -f mocks/ --cors=false                 # Disable CORS

Supported protocols: HTTP/REST, gRPC (with --proto), SOAP, MCP

The serve command exposes an SDK-compatible CRUD API at /api/v1/mocks, so Go, Python, and Java SDKs work with both standalone serve and the admin node.

Mock Management (mock) – Connected

Manage mocks on a remote Mockarty server.

mockarty-cli mock create -f mock.json             # Create/update from file
mockarty-cli mock create -f mocks/                # All files in directory
cat mock.json | mockarty-cli mock create -f -     # From stdin

mockarty-cli mock list                            # List all mocks
mockarty-cli mock list -o json                    # JSON output
mockarty-cli mock list -o wide                    # Extended table
mockarty-cli mock list --protocol grpc            # Filter by protocol

mockarty-cli mock get <mock-id>                   # Get mock by ID
mockarty-cli mock delete <mock-id>                # Delete mock
mockarty-cli mock logs <mock-id>                  # View recent invocations

mockarty-cli mock export -d backup/               # Export to directory
mockarty-cli mock import -f backup/               # Import from files

mockarty-cli mock apply -f mocks/                 # Declarative create/update
mockarty-cli mock apply -f mocks/ --prune         # + delete mocks not in files

The apply command works like kubectl apply – it creates new mocks, updates existing ones, and with --prune removes server mocks not present in your local files.

API Testing (run)

Execute API test collections with assertions and variable chaining.

mockarty-cli run -f collection.json               # Mockarty format
mockarty-cli run -f postman-export.json           # Postman v2.1 (auto-detected)
mockarty-cli run --har traffic.har                # From HAR recording
mockarty-cli run -f tests/                        # All collections in directory

Reporters (all 5 can be used simultaneously):

mockarty-cli run -f tests.json \
  --reporter cli \
  --reporter json:results.json \
  --reporter junit:report.xml \
  --reporter allure:allure-results \
  --reporter html:report.html

Exit codes: 0 = all passed, 1 = failures, 2 = execution error.

Security Fuzzing (fuzz)

Fuzz API endpoints to find vulnerabilities. Free tier: 1 thread, 2 min max.

mockarty-cli fuzz --target http://api.com --spec openapi.yaml
mockarty-cli fuzz --target http://api.com --har traffic.har --strategy all
mockarty-cli fuzz --target http://api.com --spec openapi.yaml \
  --strategy mutation --duration 5m --threads 4 \
  --out json:findings.json --out junit:fuzz-report.xml

Strategies:

Performance Testing (perf)

Run load tests with JavaScript scripts or HAR files. Free tier: 5 VU, 100 RPS max, 2 min max.

mockarty-cli perf run script.js
mockarty-cli perf run script.js --vus 50 --duration 5m
mockarty-cli perf run script.js --rps 200
mockarty-cli perf run --har traffic.har --vus 5 --duration 30s
mockarty-cli perf run script.js --out json:results.json --out html:report.html

Contract Testing (contract)

Validate mocks, verify real services, detect drift, check deploy safety, and manage an API registry.

# Validate mocks against spec (requires connected server)
mockarty-cli contract validate --spec openapi.yaml

# Verify a live service against spec
mockarty-cli contract verify --spec openapi.yaml --target http://api.staging.com
mockarty-cli contract verify --spec openapi.yaml --target http://api.staging.com --timeout 120s

# Detect mock drift — compare mocks against real API responses
mockarty-cli contract drift --target http://api.staging.com

# Check if a service version is safe to deploy
mockarty-cli contract can-i-deploy --participant user-service
mockarty-cli contract can-i-deploy --contracts contract-id-1,contract-id-2

# API registry — list published API specifications
mockarty-cli contract registry list

Exit codes: 0 = contract valid / safe to deploy, 1 = violations / drift found, 2 = execution error.

Chaos Engineering (chaos) – PRO

Run chaos engineering experiments against Kubernetes clusters. Requires a PRO license and a configured K8s cluster.

Cluster management:

# Add a K8s cluster to CLI config
mockarty-cli chaos cluster add --name staging --kubeconfig ~/.kube/config --context staging-ctx
mockarty-cli chaos cluster add --name prod --kubeconfig ~/.kube/prod.yaml \
  --allowed-namespaces app,test --denied-namespaces kube-system

# List, switch, test, inspect, remove clusters
mockarty-cli chaos cluster list
mockarty-cli chaos cluster use staging
mockarty-cli chaos cluster test
mockarty-cli chaos cluster info
mockarty-cli chaos cluster remove old-cluster

Running experiments:

# Run from flags
mockarty-cli chaos run --type pod_kill --k8s-namespace app --selector app=web --duration 5m
mockarty-cli chaos run --type network_partition --deployment my-svc --k8s-namespace app --duration 2m --auto-rollback

# Run from YAML file
mockarty-cli chaos run -f experiment.yaml

# Run from a preset
mockarty-cli chaos preset list
mockarty-cli chaos preset run --preset chaos-monkey --k8s-namespace app --selector app=web
mockarty-cli chaos preset run --preset network-partition --k8s-namespace app --selector app=api --duration 3m

Experiment lifecycle:

mockarty-cli chaos list                               # List experiments
mockarty-cli chaos list --status active               # Filter by status
mockarty-cli chaos get <experiment-id>                # Get experiment details
mockarty-cli chaos abort <experiment-id>              # Abort active experiment
mockarty-cli chaos report <experiment-id>             # Get JSON report
mockarty-cli chaos report <experiment-id> --format html --output report.html

Operator management (K8s):

mockarty-cli chaos operator install                   # Install chaos operator
mockarty-cli chaos operator install --namespace mockarty-chaos
mockarty-cli chaos operator status                    # Check operator health
mockarty-cli chaos operator uninstall                 # Remove operator

Interactive TUI:

mockarty-cli tui chaos                                # Interactive TUI

Built-in presets: chaos-monkey, network-partition, scale-to-zero, resource-pressure, rolling-restart-storm, dns-disruption.

Fault types: pod_kill, pod_kill_random, network_partition, network_delay, network_loss, deployment_restart, scale, node_drain, resource_stress, dns_disruption, io_chaos, time_chaos.

Cluster Management (cluster) – Connected

Manage a Mockarty Kubernetes cluster via the admin node API.

mockarty-cli cluster status                            # Show cluster status
mockarty-cli cluster upgrade --tag 1.3.0               # Upgrade all components
mockarty-cli cluster scale resolver --replicas 5       # Scale a component
mockarty-cli cluster restart runner                    # Rolling restart
mockarty-cli cluster logs <pod-name> --tail 100        # Stream pod logs
mockarty-cli cluster logs <pod-name> --follow          # Follow log output

# Add/remove integrations
mockarty-cli cluster add-runner --name sandbox-runner --namespace sandbox
mockarty-cli cluster add-resolver --name shared-resolver --scope admin --replicas 2
mockarty-cli cluster remove-integration sandbox-runner

Code Generation (generate)

Generate mock definitions from API specifications, HAR recordings, or Postman collections.

# From OpenAPI (via connected server)
mockarty-cli generate openapi spec.yaml -o mocks/
mockarty-cli generate openapi spec.yaml --upload    # Generate and upload to server

# From HAR recording (works locally)
mockarty-cli generate har recording.har -o mocks/

# From Postman collection (works locally)
mockarty-cli generate postman collection.json -o mocks/

Utilities

Health check:

mockarty-cli health                        # Check server health
mockarty-cli health --verbose              # Detailed info (version, uptime, license)
mockarty-cli health --wait --timeout 60s   # Wait until healthy

Wait for readiness (CI/CD):

mockarty-cli wait                                  # Wait for healthy
mockarty-cli wait --mocks user-api,order-api       # Wait for specific mocks
mockarty-cli wait --mock-count 5                   # Wait for N mocks
mockarty-cli wait --timeout 120s --interval 5s     # Custom timing

Port forwarding:

mockarty-cli tunnel --local 5770 --remote server:5770
mockarty-cli tunnel --local 50051 --remote server:50051   # gRPC

Store management (connected):

mockarty-cli store global get                          # Get all global store values
mockarty-cli store global set <key> <value>            # Set a key-value pair
mockarty-cli store global delete <key>                 # Delete a key
mockarty-cli store chain get <chain-id>                # Get chain store values
mockarty-cli store chain set <chain-id> <key> <value>  # Set a key-value pair in chain
mockarty-cli store chain delete <chain-id> <key>       # Delete a key from chain

Namespace management (connected): (alias: ns)

mockarty-cli namespace current                 # Show current namespace
mockarty-cli namespace use <name>              # Set default namespace
mockarty-cli namespace list                    # List available namespaces
mockarty-cli namespace create <name>           # Create a new namespace
# Short form:
mockarty-cli ns current

Audit log export (admin):

# CSV archive for compliance review
mockarty-cli audit export --format csv --output audit.csv

# Syslog RFC 5424 — one record per line, pipe straight to a SIEM collector
mockarty-cli audit export --format syslog > audit.log

# ArcSight CEF — direct ingestion into SIEM (Splunk/ArcSight/QRadar/MaxPatrol/KUMA/RuSIEM)
mockarty-cli audit export --format cef --output audit.cef

# Filter by user, action, resource, namespace, or time window (ms since epoch)
mockarty-cli audit export --format json --user-id u-42 --action login \
    --from 1712345678000 --to 1712431678000

Token management (PRO):

mockarty-cli token create --name "ci-runner" --expires 90d
mockarty-cli token list
mockarty-cli token delete <token-id>

Interactive TUI:

mockarty-cli tui
mockarty-cli tui --server http://localhost:8080

Navigate with arrow keys, Enter to drill down, Esc to go back, q to quit. Shortcuts: c create, e edit, d delete, n new test, u upload, / search.

Traffic sniffer (PRO):

mockarty-cli sniff --target http://real-api.com --port 9090 -o traffic.har
# Point your app to localhost:9090, Ctrl+C to stop and save HAR

AI Agent chat (PRO):

mockarty-cli agent "create a mock for GET /api/users returning a list"
mockarty-cli agent                  # Interactive chat mode

Backup/restore (PRO):

mockarty-cli backup create
mockarty-cli backup list
mockarty-cli backup download <id> -o backup.tar.gz

Platform installation (install, update, setup):

# Install platform components
mockarty-cli install mockarty                             # Download latest binary
mockarty-cli install mockarty --mode docker-compose       # Generate docker-compose.yml
mockarty-cli install mockarty --mode sqlite               # SQLite single-binary mode
mockarty-cli install --all                                # Install all components
mockarty-cli install mockarty --version 1.2.3             # Specific version

# Check for updates
mockarty-cli update

# Generate deployment config without downloading binaries
mockarty-cli setup docker-compose
mockarty-cli setup env

License management:

mockarty-cli license                        # Show current license info
mockarty-cli license features               # List all features with availability
mockarty-cli license activate <key>         # Activate a PRO license key

Version and logout:

mockarty-cli version                        # Show CLI version
mockarty-cli logout                         # Clear stored credentials

Shell completions:

mockarty-cli completion bash|zsh|fish|powershell
# Pipe output to your shell's completions directory

CI/CD Integration

GitHub Actions

name: API Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Mockarty CLI
        run: curl -sSL https://mockarty.ru/install.sh | sh

      - name: Start mock server
        run: mockarty-cli serve -f mocks/ --port 8080 &

      - name: Wait for server
        run: mockarty-cli wait --server http://localhost:8080 --timeout 30s

      - name: Run API tests
        run: |
          mockarty-cli run -f tests/ \
            --reporter cli \
            --reporter junit:report.xml \
            --reporter html:report.html

      - name: Security fuzzing
        run: |
          mockarty-cli fuzz --target http://localhost:8080 \
            --spec openapi.yaml \
            --out junit:fuzz-report.xml

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: |
            report.xml
            report.html
            fuzz-report.xml

GitLab CI

api-tests:
  image: mockarty/cli:latest
  script:
    - mockarty-cli serve -f mocks/ --port 8080 &
    - mockarty-cli wait --server http://localhost:8080
    - mockarty-cli run -f tests/ --reporter junit:report.xml --reporter allure:allure-results
    - mockarty-cli fuzz --target http://localhost:8080 --spec openapi.yaml --out junit:fuzz-report.xml
  artifacts:
    when: always
    reports:
      junit: [report.xml, fuzz-report.xml]
    paths: [allure-results/]

Exit codes make CI integration straightforward: 0 = pass, 1 = fail, 2 = error.

Drop-in replacement for allurectl / testit-cli

mockarty-cli detects the binary name it was invoked as and auto-routes
to the matching subcommand. That means a CI pipeline that currently
calls allurectl upload or testit-cli testrun create can keep its
command lines intact — just swap the binary:

# Symlink (Linux / macOS):
ln -s /usr/local/bin/mockarty-cli /usr/local/bin/allurectl
ln -s /usr/local/bin/mockarty-cli /usr/local/bin/testit-cli

# Or rename for a hermetic image:
cp mockarty-cli allurectl

# Or copy and rename in a Dockerfile:
COPY mockarty-cli /usr/local/bin/allurectl

Then point the standard env vars at your Mockarty server and run the
same commands as before:

export ALLURE_ENDPOINT=https://mockarty.company.com
export ALLURE_TOKEN=mk_...
export ALLURE_PROJECT_ID=qa-team

allurectl upload ./allure-results        # invokes 'mockarty-cli allure upload'
allurectl launch create --name "PR-42"   # invokes 'mockarty-cli allure launch create'

Same idea for TestIT — all TMS_URL / TMS_PRIVATE_TOKEN /
TMS_PROJECT_ID env vars are honoured by the testit subcommand,
so renaming the binary to testit-cli keeps the CI script unchanged.

Aliases recognised (case-insensitive, with optional .exe):

TestIT configuration UUIDs

The upstream testit-cli workflow requires a configuration UUID
(--configuration-id or TMS_CONFIGURATION_ID) for every test run.
Two helpers ship under the testit configuration subtree so CI
scripts can manage the value without the TestIT admin UI:

# Emit a fresh UUID4 and pipe straight to the env var:
export TMS_CONFIGURATION_ID="$(mockarty-cli testit configuration generate)"

# List configuration UUIDs already seen in recent external runs
# of the current namespace (sorted, deduplicated):
mockarty-cli testit configuration list --limit 100

# JSON output for scripting:
mockarty-cli testit configuration list --format json --since 2026-05-01T00:00:00Z

list scans case_context.metadata.testit.configurationId across
the namespace’s recent runs and emits the distinct values. generate
is offline — no server call, just a UUID4 — so it works in cold-boot
CI setups before the Mockarty endpoint is configured.

Free vs PRO

PRO is activated by connecting to a licensed Mockarty server or by setting MOCKARTY_LICENSE_KEY.

Output Formats

All commands that display data support the -o flag:

Examples:

mockarty-cli mock list -o json | jq '.[] | .id'
mockarty-cli mock list -o quiet | xargs -I{} mockarty-cli mock delete {}
mockarty-cli mock list -o wide

Set a default via environment: export MOCKARTY_OUTPUT=json

Global Flags

These flags work with all commands:

Troubleshooting

For connection issues, re-run the command with mockarty-cli health --verbose to see the full server response, or set MOCKARTY_OUTPUT=json to get machine-readable output.

Related Documentation

• API Reference
• SDK Guide
• Store Systems
• Contract Testing
• Chaos Engineering