Automation tools

Every action the app can do to a workspace is a JSON tool. All frontends share the same tool table: the CLI today, an MCP server later. This page lists all 71 tools. It comes from the output of postguy-cli tools --json, which is the source of truth. Run it to get the schemas in machine-readable form.

postguy-cli tools            # name, safety and title, one line per tool
postguy-cli tools --json     # {"tools":[{name,title,description,inputSchema,readOnly,destructive}]}

See the CLI reference for the commands that run the tools.

How calls work

• Arguments are one JSON object. null or no --json means {}. Any other JSON type is refused with "argument (arguments) must be a JSON object".
• Unknown arguments are refused. The error lists what is allowed: tool: unknown argument `x`; allowed: a, b. Every schema has additionalProperties: false.
• Missing required arguments are refused: tool: missing required argument `x` . Types are not checked up front. A wrong type fails inside the tool with a message like "argument x must be ..., got ...".
• Error strings say what was wrong and what is allowed. The ones you will meet most:
  • unknown tool `x`; run `postguy-cli tools`
  • no workspace is open; call workspace_open first
  • collection `ID` not found in the workspace (the same shape for every entity kind)
  • PATH is outside the allowed directory ROOT: the same text whether or not the path exists.
• Ids are opaque strings. Get them from the list tools (collection_list, env_list, run_list, ...) or from the result of a create tool. Postguy generates UUIDs. Ids from imported files can be shorter.
• Deletes go to the workspace trash. Destructive tools are flagged destructive and move data to .trash/ instead of erasing it. history_clear, console_clear and cookies_* clear their own stores. See Workspace format.
• Paths in arguments (path, out, data, paths) go through --root confinement when a root is set. Relative paths resolve against the root, and a path outside it is refused. Without --root, nothing is confined and relative paths resolve against the current directory.
• Response bodies are capped at 1 MiB in tool results (request_send, response_get, response_render_body). Use response_save to get the full decoded body.
• Cancelling: request_send, request_cancel and collection_run do not hold the session lock while they run. So request_cancel can stop an in-flight send from another thread. The CLI runs steps one after another, so this only matters for embedders.

One call is one process

Every postguy-cli call starts a new process with no workspace open. Any tool other than workspace_open fails with no workspace is open; call workspace_open first. For more than one step, use run --script. It runs a list of steps in one process and one session.

A script file cannot pass one step's result to the next step, because arguments are static JSON. Tools take ids, not names. For name-based flows, pick one of these:

• Import something, then read the ids back with a list tool (import_text or import_file, then collection_list). Do this in a second run --script call, or read the printed result lines.
• Let an agent read each step's output and generate the next script.
• Use run --collection NAME --workspace DIR, which resolves names for you (see the CLI reference).

run --script step format

A script is a JSON array of steps, or an object with a steps array. Each step is {"tool": "<name>", "args": {...}}; args is optional. Steps run in order. The first step must be workspace_open, unless the tools you call need no workspace.

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

Output is one line per step on stdout, {"step":0,"tool":"workspace_open","ok":true,"result":{...}}, then {"ok":true,"steps":3}. A failing step prints {"step":1,"tool":"...","ok":false,"error":"..."} on stderr, stops the run and exits 1.

This send flow fits in one script. The collection and request must already exist; use their real ids:

[
  {"tool": "workspace_open", "args": {"path": "work"}},
  {"tool": "request_send", "args": {"collection": "COLLECTION_ID", "request": "REQUEST_ID"}},
  {"tool": "response_get", "args": {}},
  {"tool": "history_list", "args": {"limit": 5}}
]

Tool reference

In the tables, an argument in bold is required. Safety is read-only (changes nothing), write, or destructive (deletes or clears data).

Workspace

Collections and folders

Requests

gRPC, WebSocket and OAuth

Environments and globals

Import and export

Assets

Runner

Responses, cookies, history and console

Notes on some arguments:

• ws_messages since and ws_disconnect code are declared as strings in the schema, but the implementation reads JSON numbers ("since": 12). A string value is ignored and the default is used.
• env_set_active takes {"environment": null} to clear the active environment; the schema declares the argument as a string.
• request_cancel takes the request id given to request_send, the word last, or run: followed by a collection id to cancel a collection_run.
• snippet_generate languages: curl (default), raw-http, fetch, python, go, rust, powershell, node-axios. Variables stay unresolved in the output. See Code snippets.
• collection_run with iterations omitted runs once per data row, or once without data. See Collection runner.

MCP server (planned)

The plan, from the project rules:

• It is a stdio server started as postguy-cli mcp, over the same tool table as above.
• It is opt-in: the app, the CLI and the installers never start it or register it with any client. The Windows installer explicitly registers no MCP server.
• Any future network transport would be off by default, bound to loopback and token-authenticated.

Until it ships, an agent can run postguy-cli tools --json to learn the schemas, and postguy-cli call or run --script to run them.