Command line (CLI)

The same impostor binary that runs the desktop app is also a command-line tool. With no arguments it launches the app; given a subcommand it runs headless — no window, no webview — resolving a saved request exactly the way the app does (variable scope chain

• folder inheritance) and sending it with the same HTTP engine.

This makes Impostor scriptable: run a request in CI, pipe a response into jq, or smoke-test an endpoint from a shell.

impostor run

Resolve a saved request and send it, printing the response.

impostor run <request> [--workspace <dir>] [--env <name>] [--var k=v]… [--json] [--no-secrets]

<request> may be:

• a path — absolute, or relative to the workspace ("HTTP Basics/get.request.yaml");
• a name — the request’s display name, case-insensitive ("GET / echo");
• a slug — the request file’s stem (get).

A name/slug must match exactly one request in the workspace, or the command reports the ambiguity.

# Against the workspace open in the app:
impostor run "GET / echo"

# Explicit workspace, an environment, and a one-off variable override:
impostor run login --workspace ~/work/api --env staging --var user=alice

The response prints as a status line, the response headers, then the body:

200 OK  ·  84 ms  ·  https://api.example.com/login

content-type: application/json
…

{"token":"…"}

Exit code: 0 for a 2xx response, 1 for any other status, 2 for an error (couldn’t resolve or send). So impostor run … && deploy works as a gate.

--json

Emit the whole response as one JSON object (status, timing, headers, body, and — with --no-secrets — redactedVars), ready to pipe:

impostor run health --json | jq -r .status

Binary response bodies are base64 in bodyBase64 (with body empty).

impostor ls

List the workspace’s requests as a tree (or, with --json, a flat array of { name, method, protocol, path } with workspace-relative paths).

impostor ls
impostor ls --workspace ~/work/api --json

Auth/
  GET    Bearer  (Auth/bearer.request.yaml)
HTTP Basics/
  GET    GET / echo  (HTTP Basics/get.request.yaml)
  POST   POST JSON  (HTTP Basics/post-json.request.yaml)

Choosing the workspace

Every command resolves its workspace in this order:

1. an explicit --workspace <dir>;
2. otherwise, the workspace currently open in the app — Impostor writes a small pointer file while it’s running, so impostor run login “just works” against whatever you have open;
3. otherwise, a clear error (“no workspace — open one in Impostor, or pass —workspace”).

The pointer is cleared when you quit the app, so the no---workspace form only resolves while Impostor is open. Pass --workspace explicitly for use in CI or scripts.

Variables, secrets, and scripts

• --var k=v overrides a variable for this run and takes precedence over every other scope (globals, folder, environment, and request-local). Repeat it for several.
• Secrets resolve by default — a vault unlock may prompt your OS keychain, which an interactive terminal can answer. Pass --no-secrets to blank secret-backed variables instead; their names are then reported (as a note, or in redactedVars under --json).
• Scripts don’t run headless: pre/post-request scripts are skipped and ƒx value scripts resolve empty, because the terminal has no way to review-and-enable an untrusted script the way the app does. (Everything else — auth, inheritance, variable substitution, TLS — is fully applied.)