Command line

Postguy has two programs:

See Installation to find where each one is installed.

postguy (desktop app)

postguy [--workspace DIR] [--control FILE]

• With no --workspace, the app picks a folder in this order:
  1. ./postguy-workspace, if that folder exists.
  2. ~/postguy-workspace (%USERPROFILE%\postguy-workspace on Windows).
  3. The relative path postguy-workspace, only when no home folder is known.
• The Flatpak build adds --workspace "${XDG_DATA_HOME:-$HOME/.local/share}/postguy-workspace" unless you pass --workspace yourself.
• These are the only two flags. Other arguments are ignored. There is no --help or --version.
• If the control channel cannot start, the app still runs. It prints control channel disabled: ... to stderr and shows the same text in the status bar.

postguy-cli

postguy-cli has no --help and no --version. With no command, or an unknown command, it prints this usage to stderr and exits 2:

usage:
  postguy-cli tools [--json]
  postguy-cli call <tool> --json '<args>' [--root DIR]
  postguy-cli run --script FILE [--root DIR]
  postguy-cli run --collection ID_OR_NAME --workspace DIR [--folder F] [--environment E] [--iterations N] [--delay MS] [--data FILE] [--bail] [--requests ID,ID] [--reporters cli,json,junit,html,csv,xlsx,pdf] [--out DIR] [--root DIR]
  postguy-cli fuzz-target <name> <seed-file>   (dev tooling)
  postguy-cli ui --control FILE inspect|command ID|set KEY=VALUE|screenshot --out FILE|click X Y|key NAME|type TEXT [--root DIR]

Run `postguy-cli tools` for the tool table; `ui` talks to an app launched with `--control FILE`.

Exit codes

--root DIR

--root DIR limits every path argument to one directory. The directory is created if it does not exist.

• Relative paths resolve against the root, not the current directory.
• Absolute paths are accepted only inside the root; .. is resolved before the check, and symlinks that point outside are refused.
• A path outside the root is refused with PATH is outside the allowed directory ROOT. The message is the same whether or not the path exists, so a confined caller cannot probe the disk.
• It applies to the --script file itself, workspace_open paths, imports, exports, --workspace, --data and --out.
• Without --root, nothing is confined and relative paths resolve against the current directory.
• ui uses --root only for the screenshot --out path.

The workspace's config folder is always <workspace>/.postguy-config in a postguy-cli session.

tools

postguy-cli tools          # one line per tool
postguy-cli tools --json   # full schemas

Plain output is one line per tool: the name (padded to 20 columns), the safety (read-only, write or destructive) and the title. With --json it prints one JSON object, {"tools":[{"name","title","description","inputSchema","readOnly","destructive"}]}. Exit code is 0. The tools are described in Automation tools.

call

postguy-cli call <tool> --json '<args>' [--root DIR]

Runs one tool and prints its JSON result on stdout (exit 0).

Each call starts a new process with no workspace open. On its own, only workspace_open (and tools that need no workspace) can succeed. For anything with more than one step, use run --script. See Automation tools.

postguy-cli call workspace_open --json '{"path":"work"}' --root /tmp/pg

run --script

postguy-cli run --script FILE [--root DIR]

Runs a JSON script of tool steps in one process and one session.

• FILE is a JSON array of steps, or an object with a steps array, at most 8 MiB. Each step is {"tool": "<name>", "args": {...}}; args is optional.
• Steps run in order. The first step normally is workspace_open.
• Each successful step prints one stdout line {"step":N,"tool":"...","ok":true,"result":{...}}. After the last step it prints {"ok":true,"steps":N}.
• The first failing step prints {"step":N,"tool":"...","ok":false,"error":"..."} on stderr, stops the run and exits 1. A step without a tool also exits 1.
• A script that is not readable, not JSON, not an array or {"steps":[...]}, or outside --root exits 2.

[
  {"tool": "workspace_open", "args": {"path": "work"}},
  {"tool": "collection_create", "args": {"name": "Smoke"}},
  {"tool": "collection_list", "args": {}}
]

postguy-cli run --script steps.json --root .

run --collection

postguy-cli run --collection ID_OR_NAME --workspace DIR [options]

This opens the workspace, runs the collection with the collection runner, and prints or writes reports. --collection and --workspace are both required.

• cli prints the text summary to stdout: Iteration i/n, ✓ name or ✗ name: reason lines, and a totals line.
• Every other reporter writes <out>/postguy-run-<run id>.<ext> and prints wrote <path>. The extension is the reporter name, except junit, which uses .xml.
• The run is also stored in the workspace (newest 20 per collection). See Workspace format.

Name errors list the candidates, for example:

no collection `X`; known: Smoke (col1)
`X` matches 2 collections; use an id: Smoke (col1), Smoke (col2)

postguy-cli run --collection "Smoke" --workspace ~/postguy-workspace \
  --environment dev --reporters cli,junit --out reports

For a CI step, see Collection runner.

ui

postguy-cli ui --control FILE inspect
postguy-cli ui --control FILE command <id>
postguy-cli ui --control FILE set <key>=<value>
postguy-cli ui --control FILE screenshot --out FILE [--root DIR]

This talks to an app started with postguy --control FILE.

• --control FILE is required.
• On success it prints the response body and exits 0. Any error exits 2.
• On Unix the control file must be owner-only. Otherwise the client refuses to read the token.
• click X Y, key NAME and type TEXT are accepted by the client but refused by the app.

The actions, keys and limits are in UI control channel.

fuzz-target

postguy-cli fuzz-target <name> <seed-file> is a development command used by cargo xtask fuzz. It is not for end users.

• The names are url, vars, curl, script, data, openapi and har.
• Exit 0 means the code survived the input. Exit 2 means an error or bad usage.

mcp

Environment variables