CLI

The rustybin binary doubles as a command-line tool for mocks: rustybin mock .... validate, init, sample and check-config work offline on local files; the other commands call the control API of a running instance. rustybin mock --help prints the summary.

The examples run in a directory holding inventory.yaml (the spec shown in Configuration as code), against a server on http://localhost:8080 with the admin token change-me. The outputs are real.

Offline commands

validate

Parses a spec and runs the deploy checks with default settings: the operations with their ids and check status, every finding, and a summary. Exit code 0 (warnings allowed), 1 when the checks report errors, 2 when the file cannot be read or is not an OpenAPI 3 document.

rustybin mock validate inventory.yaml

Inventory 2.0.0 (OpenAPI 3.1.0)
3 operation(s), server prefix "/v2", suggested name "inventory"
  GET     /health                                  health                   ok
  GET     /items                                   listItems                ok
  GET     /items/{sku}                             getItem                  ok
0 error(s), 0 warning(s)

A spec with problems (an example that breaks its schema, an undeclared path parameter, an operation without responses):

Bad 1 (OpenAPI 3.0.3)
2 operation(s), server prefix "", suggested name "bad"
  GET     /a                                       a                        warning
          Warning: the spec example for 200 does not match the schema (/ expected integer, got string "nope")
  GET     /b/{x}                                   get_b_x                  ok
warning: GET /b/{x}: path parameter {x} is not declared (treated as a string)
warning: GET /b/{x}: no responses documented, answers 200 with an empty body
0 error(s), 3 warning(s)

$ rustybin mock validate swagger.json
rustybin mock: Swagger 2.0 is not supported yet: convert the spec to OpenAPI 3 first (for example with swagger2openapi)

init

Prints a rustybin.yaml for the spec: the name (--name, default from info.title), the spec path as you typed it (keep the file next to the spec, or fix the path: it is relative to the config file), --generated for generated responses and --secure to switch mocked security on.

rustybin mock init inventory.yaml --name docs-cli --generated

# rustybin.yaml for Inventory (3 operations)
version: 1
mocks:
- name: docs-cli
  spec: inventory.yaml
  enabled: true
  responses:
    mode: generated
    validate_requests: warn
  security:
    enabled: false
    mode: spec

sample

Prints a valid response for one operation (--status picks a documented status, --generated and --seed N switch to generated data), or with --request a valid request. The first line, on stderr, says where the body came from.

rustybin mock sample inventory.yaml getItem --status 404
rustybin mock sample inventory.yaml getItem --request

# GET /items/{sku} -> 404 (example)
{
  "title": "unknown SKU"
}
{
  "method": "GET",
  "path": "/v2/items/SKU-0",
  "query": [],
  "headers": []
}

$ rustybin mock sample inventory.yaml getItem --generated --seed 7
# GET /items/{sku} -> 200 (generated)
{
  "sku": "SKU-0",
  "name": "Margaret Hamilton",
  "quantity": 8,
  "updated": "2026-09-14T09:30:00Z"
}

check-config

Loads a config file the way the server does (environment variables expanded, spec paths relative to the file) and compiles every mock. Exit code 1 when a mock does not load or its checks report errors. The file defaults to ./rustybin.yaml.

INVENTORY_API_KEY=k1 rustybin mock check-config rustybin.yaml

inventory: Inventory (3 operations): 0 error(s), 0 warning(s)

Remote commands

Errors print the server's message and exit with code 2 (rustybin mock: HTTP 401: admin token required: ...).

push

Applies a config file (default ./rustybin.yaml) with POST /_rustybin/mocks/apply: spec files are read locally and inlined, so the server never needs access to them, and environment variables are expanded. --prune deletes the mocks created through the API or console that the file does not list. Pushing an unchanged file changes nothing.

export RUSTYBIN_SERVER="$BASE" RUSTYBIN_TOKEN="$ADMIN_TOKEN"
rustybin mock push rustybin.yaml
rustybin mock push rustybin.yaml

created: docs-cli
unchanged: docs-cli

list

rustybin mock list

docs-cli                 live      3 ops      0 req  http://localhost:8080/mock/docs-cli/v2
inventory                live      3 ops      0 req  http://localhost:8080/mock/inventory secured
petstore                 live      6 ops      0 req  http://localhost:8080/mock/petstore/v1
weather                  live      1 ops      0 req  http://localhost:8080/mock/weather

Columns: name, state (live, off, draft), operations, captured requests, URL, then secured and (draft changes) when they apply. --json prints the GET /_rustybin/mocks response:

rustybin mock list --json

enable, disable, deploy, delete, export

rustybin mock disable docs-cli
curl -s -o /dev/null -w '%{http_code}\n' "$BASE/mock/docs-cli/v2/items"
rustybin mock enable docs-cli
curl -s -o /dev/null -w '%{http_code}\n' "$BASE/mock/docs-cli/v2/items"

docs-cli: disabled
503
docs-cli: enabled
200

deploy publishes the draft (add --force to deploy despite check errors); export prints one mock, or every mock without a name, as rustybin.yaml:

rustybin mock deploy docs-cli
rustybin mock export docs-cli > docs-cli.rustybin.yaml

rustybin mock delete docs-cli

docs-cli: deleted

In a container

The image has the same binary on its PATH, and docker exec inherits the container's environment: a RUSTYBIN_ADMIN_TOKEN set on the container is used as the token, and the default server (http://localhost, or the port in RUSTYBIN_HTTP_PORT) is the server in the container:

docker exec rustybin rustybin mock list
docker exec rustybin rustybin mock disable orders
docker exec rustybin rustybin mock check-config /app/rustybin.yaml

From the host, the same commands work against the published port:

rustybin mock list --server http://localhost:8080