Update to Postman

{
  "name": "flows",
  "description": "Runs, deploys, and debugs Postman Flows from the command line — executing a flow file locally, triggering a deployed flow over its webhook, deploying one so it becomes callable, and tracing a failed run to the block that broke. Use when the user names a flow and an action (\"run the Checkout flow\", \"deploy this flow\", \"why did that flow run fail\", \"what flows do I have\"). Covers `postman flows list`, `run`, `trigger`, `deploy`, `update`, `list-runs`, and `get-run`.",
  "included_files": [
    {
      "relative_path": "reference/flow_cli_flags.md",
      "size_in_bytes": 5616
    }
  ],
  "skill_md_contents": "---\nname: flows\ndescription: Runs, deploys, and debugs Postman Flows from the command line — executing a flow file locally, triggering a deployed flow over its webhook, deploying one so it becomes callable, and tracing a failed run to the block that broke. Use when the user names a flow and an action (\"run the Checkout flow\", \"deploy this flow\", \"why did that flow run fail\", \"what flows do I have\"). Covers `postman flows list`, `run`, `trigger`, `deploy`, `update`, `list-runs`, and `get-run`.\n---\n\n# Postman Flows\n\n## Overview\n\nListing flows, running them, deploying them so they become callable, and\ntracing a failed run to the block that caused it — all through\n`postman flows`.\n\n## Core knowledge\n\nA flow is a graph of blocks, not a script. That single fact drives the rest of\nthis skill: a flow has two independent execution paths, and its HTTP response\ndescribes one block rather than the whole graph, so debugging takes a\ndifferent command than running.\n\n### Local file vs deployed artifact\n\n`run` and `trigger` are not two ways to execute one flow. Postman Flows has\ntwo Native Git modes, and they are isolated from each other:\n\n- **Cloud View** (the default) syncs flows to Postman Cloud, which is what\n  makes them shareable and **deployable** — so Cloud View is the only side\n  `deploy`, `trigger`, `update`, `list-runs` and `get-run` ever address.\n- **Local View** stores flows as JSON in a local Git repo, updated as they are\n  edited. Those flows **cannot be shared or deployed**, have no snapshots, and\n  are isolated from the flows in Cloud View.\n\n| | `flows run <path>` | `flows trigger <flowId>` |\n| --- | --- | --- |\n| Executes | a flow JSON file on this machine | the cloud-deployed flow, via its webhook |\n| Returns | status, output, test results, exit code | Run ID + HTTP status + response body |\n| Observability | own stdout, `--output`, `--reporters` | `get-run`, per block |\n| Environment file | `-e/--environment` | not supported |\n\n`run` exits nonzero on failure, which is what lets a CI job gate on it.\n`trigger` goes through the real webhook URL, so it exercises the deployed path\nend-to-end — auth and trigger configuration included — and registers a cloud\nrun that `get-run` can explain block by block.\n\n`postman init` scaffolds `postman/flows/`, and Postman's `flows run` examples\nuse that path. Note what puts files there: the Git-connected Flows experience\nis **desktop-app only**, so `postman/flows/*.json` is written by the desktop\napp's Local View, not by the CLI — `workspace push`/`pull` carry no flows\nhandling whatever else they sync. Don't tell a user to `workspace pull` to\nobtain a flow file.\n\n### What deploying buys, and what it requires\n\nDeploying puts the flow in Postman's cloud and attaches an HTTP trigger, which\nis what makes it reachable by schedules, webhooks, third-party apps, and other\nAPIs — the flow stops being something a human opens and becomes callable\ninfrastructure.\n\nThree preconditions sit outside the CLI, so no flag or retry satisfies them:\nthe flow must be in Cloud View, its Start block must be configured with an API\nrequest trigger, and its canvas must have a Response block. Check these before\nre-running a failed deploy with different arguments.\n\n`--path` is a suffix appended to a generated base URL, not a full URL.\n\n### Inputs: `-i` versus a scenario\n\nA scenario is a named input set stored **in the flow definition**, generated\nwhen someone adds an input to the Start block. Because it travels with the\nflow, `-s \"Staging\"` is reproducible across invocations and across people,\nwhere `-i key=value` is per-invocation. Start-block inputs can be declared\nsecret, which is what `--show-secrets` unmasks in dry-run output.\n\nPrecedence: `-s` supplies payload, headers, and query; `--headers` and\n`--query` override it; `-i`/`-f` override its values.\n\n### Identifiers\n\n`flows list` is the only way to turn a flow name into an id —\n`.postman/resources.yaml` maps collections to cloud ids but has no flows\nsection, so there is nothing local to read. Both `list` and `list-runs`\n**require** `-w/--workspace`; take that id from `workspace.id` in\n`.postman/resources.yaml`, which `bootstrap` records.\n\nRun IDs have no single documented shape (`session-abc123` and `main/1a123ab1`\nboth appear in Postman's own material). Use whatever `trigger` or `list-runs`\nprinted, verbatim, and apply the same rule to flow ids.\n\n### Plan and permission gating\n\n`flows run` is documented as Enterprise-only, and the cloud subcommands need\n`postman login`. `Access denied. Please check your permissions for the\nspecified resource.` on *every* workspace is a credential-scope or plan\nsignal, not a wrong-workspace signal — and never means the workspace has no\nflows.\n\n## Deploying: propose, confirm, then verify\n\nDeploy is the one multi-phase workflow here, because it is mutating and\nbecause its result is only half-useful without the follow-up check.\n\n1. **Resolve the id.** `flows list --workspace <id> --filter \"Checkout\"`. On\n   multiple matches, show name + id + last-updated and let the user pick.\n2. **Propose the path.** Derive it from the flow name — \"Checkout\" →\n   `/checkout` — so the user is confirming a concrete value rather than\n   answering an open question. Raise `--auth` here if the trigger will be\n   reachable by anyone who learns the URL.\n3. **Confirm, then run** `flows deploy <flowId> --path /checkout`.\n4. **Report the Trigger URL and whether the trigger is enabled.** A deploy can\n   land with the trigger off, which looks identical to a broken deploy at call\n   time. If it is off, offer `flows update <flowId> --trigger on`.\n\nWhen the deploy existed only so the flow could be run, trigger it in the same\nturn and report the Run ID — deploy-then-trigger is one job.\n\n## Running and triggering\n\nShow the command before running it, and map the request onto flags: inputs to\n`-i`, a payload file to `-f`, query to `-q`, headers to `--headers`, a named\nscenario to `-s`.\n\n```bash\npostman flows run postman/flows/checkout.json -i amount=4200\npostman flows trigger <flowId> -i amount=4200\n```\n\n`run` is documented as Enterprise-only, so check the plan before building a\nworkflow on the local path. Where the flow is already in Cloud View, `trigger`\ncovers the gap; a Local View flow has no such fallback, since it cannot be\ndeployed.\n\n`-n/--dry-run` on `trigger` prints the resolved URL and payload without\nsending — worth reaching for when a flow writes to real systems, since a\ntrigger is not a read-only probe. For CI, `--output json` and `--reporters\nhtml` persist results, and `--workspace` is required if the flow contains\nconnector blocks (it fails at the block, not at startup).\n\nReport the Run ID on every trigger, including successes; it is the only handle\non the run afterwards.\n\nTwo failures are recoverable rather than terminal, and both recover through a\nconfirmed mutation. A 404 hinting `To deploy it, run: postman flows deploy`\nmeans the flow exists but was never deployed — offer the deploy above, then\nre-trigger. A disabled-trigger error means it is deployed but not accepting\ncalls — offer `flows update <flowId> --trigger on`, then trigger.\n\n## Debugging a run\n\nA trigger's response body is the Response block's output. A flow can answer\n200 with a failed block upstream, and a 500 says nothing about which block\nproduced it — so read the run, not the response.\n\n```bash\npostman flows list-runs --workspace <id> --flow <flowId> --range 3d\npostman flows get-run --run-id <runId> --logs\n```\n\n`list-runs` recovers a Run ID nobody wrote down; its `--range` defaults to\n`1h`, so widen it before concluding a run is missing. Start `get-run` without\n`--logs` and add them when the summary does not explain the failure;\n`--filter` narrows to a block-id prefix.\n\nReport the failing block, the reason, and the run status:\n\n```\nRun session-abc123 — failed\n  Failing block: \"HTTP Request (Get Orders)\"\n  Reason:        downstream returned 504 after 10s timeout\n  Status:        error\n```\n\n## Critical Rules\n\n1. **Resolve ids, never infer them.** A name is not an id, and no id format is\n   documented well enough to validate against. Ambiguous name → present\n   candidates and ask.\n2. **`deploy` and `update` need explicit confirmation.** They change what the\n   flow does for every caller: a deploy exposes a trigger path, `--trigger\n   on|off` starts or stops accepting calls, and `--auth off` removes\n   authentication from a live trigger.\n3. **Report the failing block, not the log.** `--logs` output is input to your\n   analysis; the user needs the block, the reason, and the status.\n4. **Surface CLI errors verbatim** and read them literally. \"Flow file not\n   found\", a required-option error, and \"Access denied\" have three different\n   fixes, and only the last is about permissions.\n5. **A missing or unauthenticated CLI is `bootstrap`'s job** — route there\n   rather than improvising an install or a second login.\n\n## Anti-patterns\n\n1. **Don't substitute `run` for `trigger` when a flow isn't deployed.** A\n   green local run says nothing about the deployed path a caller hits, and a\n   Local View flow cannot be deployed at all.\n2. **Don't hunt for a different workspace id when access is denied across\n   every workspace you try.** A blanket denial points at the credential's\n   scope or the plan, not at the id.\n3. **Don't pass `-x/--suppress-exit-code` in CI.** It makes a failed flow\n   report success to the pipeline, which removes the only thing gating it.\n4. **Don't put reusable inputs on the command line.** A payload that matters\n   more than once belongs in a Start-block scenario, where it travels with the\n   flow.\n\n## Reference\n\n- [Flows CLI flags](reference/flow_cli_flags.md) — full flag tables per\n  subcommand, the BETA dataset-iteration flags, and the short-flag collisions\n  between subcommands. Read before composing a command with flags not shown\n  above.\n- `bootstrap` skill — CLI install, login, and the workspace id these commands\n  require.\n- `api-discovery` skill — `postman search flows` finds a flow by text across\n  Postman, a different dataset from `flows list`'s workspace enumeration.\n"
}