Terminal
Terminal/Skill
Runs, deploys, and debugs Postman Flows from the command line, including tracing a failed run to the block that broke.
By Postman
Works with
npx skills add postmanlabs/postman-plugin --skill flowsListing flows, running them, deploying them so they become callable, and
tracing a failed run to the block that caused it — all through
postman flows.
A flow is a graph of blocks, not a script. That single fact drives the rest of this skill: a flow has two independent execution paths, and its HTTP response describes one block rather than the whole graph, so debugging takes a different command than running.
run and trigger are not two ways to execute one flow. Postman Flows has
two Native Git modes, and they are isolated from each other:
deploy, trigger, update, list-runs and get-run ever address.flows run <path> | flows trigger <flowId> | |
|---|---|---|
| Executes | a flow JSON file on this machine | the cloud-deployed flow, via its webhook |
| Returns | status, output, test results, exit code | Run ID + HTTP status + response body |
| Observability | own stdout, --output, --reporters | get-run, per block |
| Environment file | -e/--environment | not supported |
run exits nonzero on failure, which is what lets a CI job gate on it.
trigger goes through the real webhook URL, so it exercises the deployed path
end-to-end — auth and trigger configuration included — and registers a cloud
run that get-run can explain block by block.
postman init scaffolds postman/flows/, and Postman's flows run examples
use that path. Note what puts files there: the Git-connected Flows experience
is desktop-app only, so postman/flows/*.json is written by the desktop
app's Local View, not by the CLI — workspace push/pull carry no flows
handling whatever else they sync. Don't tell a user to workspace pull to
obtain a flow file.
Deploying puts the flow in Postman's cloud and attaches an HTTP trigger, which is what makes it reachable by schedules, webhooks, third-party apps, and other APIs — the flow stops being something a human opens and becomes callable infrastructure.
Three preconditions sit outside the CLI, so no flag or retry satisfies them: the flow must be in Cloud View, its Start block must be configured with an API request trigger, and its canvas must have a Response block. Check these before re-running a failed deploy with different arguments.
--path is a suffix appended to a generated base URL, not a full URL.
-i versus a scenarioA scenario is a named input set stored in the flow definition, generated
when someone adds an input to the Start block. Because it travels with the
flow, -s "Staging" is reproducible across invocations and across people,
where -i key=value is per-invocation. Start-block inputs can be declared
secret, which is what --show-secrets unmasks in dry-run output.
Precedence: -s supplies payload, headers, and query; --headers and
--query override it; -i/-f override its values.
flows list is the only way to turn a flow name into an id —
.postman/resources.yaml maps collections to cloud ids but has no flows
section, so there is nothing local to read. Both list and list-runs
require -w/--workspace; take that id from workspace.id in
.postman/resources.yaml, which bootstrap records.
Run IDs have no single documented shape (session-abc123 and main/1a123ab1
both appear in Postman's own material). Use whatever trigger or list-runs
printed, verbatim, and apply the same rule to flow ids.
flows run is documented as Enterprise-only, and the cloud subcommands need
postman login. Access denied. Please check your permissions for the specified resource. on every workspace is a credential-scope or plan
signal, not a wrong-workspace signal — and never means the workspace has no
flows.
Deploy is the one multi-phase workflow here, because it is mutating and because its result is only half-useful without the follow-up check.
flows list --workspace <id> --filter "Checkout". On
multiple matches, show name + id + last-updated and let the user pick./checkout — so the user is confirming a concrete value rather than
answering an open question. Raise --auth here if the trigger will be
reachable by anyone who learns the URL.flows deploy <flowId> --path /checkout.flows update <flowId> --trigger on.When the deploy existed only so the flow could be run, trigger it in the same turn and report the Run ID — deploy-then-trigger is one job.
Show the command before running it, and map the request onto flags: inputs to
-i, a payload file to -f, query to -q, headers to --headers, a named
scenario to -s.
postman flows run postman/flows/checkout.json -i amount=4200
postman flows trigger <flowId> -i amount=4200
run is documented as Enterprise-only, so check the plan before building a
workflow on the local path. Where the flow is already in Cloud View, trigger
covers the gap; a Local View flow has no such fallback, since it cannot be
deployed.
-n/--dry-run on trigger prints the resolved URL and payload without
sending — worth reaching for when a flow writes to real systems, since a
trigger is not a read-only probe. For CI, --output json and --reporters html persist results, and --workspace is required if the flow contains
connector blocks (it fails at the block, not at startup).
Report the Run ID on every trigger, including successes; it is the only handle on the run afterwards.
Two failures are recoverable rather than terminal, and both recover through a
confirmed mutation. A 404 hinting To deploy it, run: postman flows deploy
means the flow exists but was never deployed — offer the deploy above, then
re-trigger. A disabled-trigger error means it is deployed but not accepting
calls — offer flows update <flowId> --trigger on, then trigger.
A trigger's response body is the Response block's output. A flow can answer 200 with a failed block upstream, and a 500 says nothing about which block produced it — so read the run, not the response.
postman flows list-runs --workspace <id> --flow <flowId> --range 3d
postman flows get-run --run-id <runId> --logs
list-runs recovers a Run ID nobody wrote down; its --range defaults to
1h, so widen it before concluding a run is missing. Start get-run without
--logs and add them when the summary does not explain the failure;
--filter narrows to a block-id prefix.
Report the failing block, the reason, and the run status:
Run session-abc123 — failed
Failing block: "HTTP Request (Get Orders)"
Reason: downstream returned 504 after 10s timeout
Status: error
deploy and update need explicit confirmation. They change what the
flow does for every caller: a deploy exposes a trigger path, --trigger on|off starts or stops accepting calls, and --auth off removes
authentication from a live trigger.--logs output is input to your
analysis; the user needs the block, the reason, and the status.bootstrap's job — route there
rather than improvising an install or a second login.run for trigger when a flow isn't deployed. A
green local run says nothing about the deployed path a caller hits, and a
Local View flow cannot be deployed at all.-x/--suppress-exit-code in CI. It makes a failed flow
report success to the pipeline, which removes the only thing gating it.bootstrap skill — CLI install, login, and the workspace id these commands
require.api-discovery skill — postman search flows finds a flow by text across
Postman, a different dataset from flows list's workspace enumeration.