Command line

The getman command runs saved requests from a terminal, compares API contracts, manages change packages and starts the mock server and the MCP server. It uses the same engine as the desktop app, so the results match.

Install and check

Install the command from Project settings → Command line & agents → Install command-line tool. It writes a getman launcher to ~/.local/bin (on Windows, %LOCALAPPDATA%\Getman\bin). If Getman says that folder is not on your PATH, add it. The CLI needs Node.js 20 or later.

getman help
getman projects

Commands that run requests need the engine, which is built into the installed app. Commands that only read files, such as contract diff and change list, do not need it.

Run requests

A target is a request, folder or collection. Give its ID from getman ls, or its name path such as Shop API/Orders/Get order. A bare name works when it is unique.

export GETMAN_VAR_password=…
getman run "Shop API" --workspace getman --env Local
getman run "Shop API/Orders/Get order" --workspace getman --env Local --json

Folders and collections run their requests in tree order. Variables set by post-response scripts carry over to the next request in the same run.

Options

Option	Meaning
--project P	Project ID or name, when you use the app database.
--workspace DIR	A sync folder, such as getman. Reads its files and secrets from GETMAN_VAR_<KEY>.
--env NAME	Environment name or ID.
--var k=v	A runtime variable. Repeatable. It is not saved.
--iterations N, --data FILE	Repeat a run, or run one iteration per row of a CSV or JSON file.
--timeout MS, --delay MS	Request timeout, and a pause between requests.
--bail	Stop at the first failed request.
--allow-mutations	Send POST, PUT, PATCH and DELETE to production-kind environments.
--json, --include-bodies	Print JSON output, and include response bodies in it.
--no-secrets	Do not read secret values. They stay blank.
--engine PATH	The engine binary to use.

Status codes and test results

A 4xx or 5xx response fails the request, unless an enabled status assertion expects that status, such as Status equals 401 for a request that tests the unauthorized case. The desktop app, the runner, --bail, MCP and change evidence use the same rule.

Exit codes

Code	Meaning
0	Every request passed.
1	A test failed.
2	A request or script failed: connection, timeout, TLS or script error.
3	Usage or configuration error, such as an unknown project or environment, or no engine.
4	A production mutation was skipped.
5	Saved secrets are locked for the command line. Turn on access in Project settings → Command line & agents, or use --no-secrets.
130	Interrupted with Ctrl-C.

When several conditions apply, the first in this order wins: 130, 2, 4, 1, 0.

Production gate

Mutating requests (anything except GET, HEAD and OPTIONS) to environments in the project’s confirmMutationsIn list are not sent. The default list is production. The request is reported as skipped, and the run exits with 4. Use --allow-mutations only when you mean to change production data. Agents have their own approval flow, described in the MCP server.

JSON output

With --json, a run prints one object with the schema getman.run/v1:

{
  "schema": "getman.run/v1",
  "ok": false,
  "exitCode": 1,
  "source": "workspace",
  "environment": { "name": "Local", "kind": "local" },
  "summary": { "total": 2, "passed": 1, "failed": 1, "errors": 0, "skipped": 0, "cancelled": 0 },
  "steps": [
    { "name": "Login", "method": "POST", "outcome": "passed", "status": 200, "tests": [{ "name": "has token", "passed": true }] }
  ]
}

Errors that happen before the run print a getman.error/v1 object with the exit code and a message.

Contracts

getman contract export --workspace getman --out openapi.yaml
getman contract diff before.yaml after.yaml --fail-on breaking

contract export writes OpenAPI 3.1 YAML to standard output, or to --out. contract diff compares two OpenAPI files. With --fail-on breaking, it exits 1 when a breaking change exists. --fail-on potentially-breaking also counts potentially breaking changes.

Change packages

getman change new --workspace getman --title "…" --migration "…" --author "Alice (backend)"
getman change list --workspace getman
getman change show GT-SHOP-001 --workspace getman
getman change verify GT-SHOP-001 --workspace getman --env Local
getman change report GT-SHOP-001 --workspace getman --consumer web --status verified
getman change state GT-SHOP-001 published --workspace getman
getman change validate --workspace getman

• change new diffs the project against contracts/openapi.yaml, writes the change file, and prints the new ID. It refuses when nothing changed.
• change verify runs the requests that the change touches, and records the run as evidence. Its exit code is the run’s exit code.
• change report records a consumer’s status: pending, in-progress, reported, verified or blocked.
• change state moves a change to draft, published or withdrawn.
• change validate checks the change files and the contract for conflict markers, invalid YAML, duplicate IDs and mismatched file names. It exits 3 when it finds problems.

Write commands need --workspace. The CLI never writes the app database. Details are in change packages.

Mock server

getman mock --workspace getman --port 4010
getman mock --from openapi.yaml

The mock serves the saved response examples on 127.0.0.1. The default port is 4010. Stop it with Ctrl-C, which exits with 130.

Use in CI

contract diff and change validate can run from a built bundle without an engine: yarn build:cli, then node dist-cli/getman.mjs contract diff …. run and change verify need an engine binary. Build it with cd src-tauri && cargo build --features engine --bin engine. CI use has not been tested yet.