@postman/postman-plugin 0.2.1 → 0.3.0

package/skills/api-simulation/reference/sim_yaml_schema.md

@@ -0,0 +1,112 @@
+# `.sim.yaml` schema
+
+The file `postman simulation run <filepath>` reads. It lives in
+`postman/simulations/NAME.sim.yaml`, beside the `postman/mocks/` folders it
+composes. `postman simulation create` writes one; the Postman app writes the
+same shape with `id:` fields added.
+
+```yaml
+id: 01a110fc-e3f5-77eb-af59-0a711a509960        # written by the Postman app
+simulation: checkout-dev
+routing: path
+mocks:
+  - id: 01a110fc-e344-72ca-9d0c-1bb83b99ec2a    # written by the Postman app
+    routeKey: products
+    path: ../mocks/products/config.yaml
+    scenarios:
+      - path: ../mocks/products/default.js
+  - routeKey: shopping-cart
+    path: ../mocks/shopping-cart/config.yaml
+```
+
+## Root
+
+| Key | Required | Notes |
+| --- | --- | --- |
+| `simulation` | Yes | The simulation's name. |
+| `mocks` | Yes | Non-empty list of members. |
+| `routing` | No | `path` (default) or `header`. Any other value means `path`. |
+| `id` | No | The simulation's id in its workspace. A local run ignores it; leave it as written. |
+
+## Member
+
+| Key | Required | Notes |
+| --- | --- | --- |
+| `path` | Yes | The mock's `config.yaml`, or a `.js` handler. Relative paths resolve from the `.sim.yaml`'s folder, then from the working directory. `file` is a legacy alias. |
+| `routeKey` | No | The member's address. Lowercase letters, digits, `-` and `_`, at most 64 characters, unique per simulation. Defaults to the kebab-cased name. |
+| `name` | No | Display name. Defaults to the mock's folder name for a `config.yaml`, else the file name. Must be unique. |
+| `scenarios` | No | Fault conditions, below. |
+| `id` | No | The mock's id in its workspace. A local run ignores it. |
+| `port` | No | Ignored by `simulation run`, which gives each member an internal port. |
+
+## Routing
+
+- **`path`**: a member is at `http://localhost:<port>/<routeKey>`. The first
+  path segment selects the member and is stripped, so `/payments/cart` reaches
+  the `payments` member as `/cart`. Point the service's base URL for that
+  dependency at `http://localhost:<port>/<routeKey>`.
+- **`header`**: every member shares `http://localhost:<port>`, and the caller
+  picks one with an `x-mock-slug: <routeKey>` header. Use it only when the
+  caller can send that header.
+
+The router answers on its own, without reaching a member:
+
+| Response | Cause |
+| --- | --- |
+| `400 {"error":"Prefix the request path with the member routing token, e.g. /<routeKey>/path."}` | No routeKey under `path` routing: the path was `/`. Under `header` routing the error asks for the `x-mock-slug` header instead. |
+| `404 {"error":"Unknown simulation member '<x>'.","available":[...]}` | `<x>` isn't a routeKey. Under `path` routing this is often a client that dropped the base URL's path, so `<x>` is the endpoint's own first segment. |
+
+## `scenarios`
+
+Each entry is a selection, and only its `overrides.conditions` inject faults:
+
+```yaml
+scenarios:
+  - overrides:
+      conditions:
+        latency:
+          delay_ms: 250              # hold each request 250 ms, then go on
+        error:
+          status_code: 503           # every request fails with 503
+        rate_limit:
+          requests_per_minute: 30    # the 31st request in a minute gets 429
+        chaos:
+          failure_rate: 10           # 10% of requests fail with 500
+```
+
+This example sets all four to show their fields. They run in a fixed order,
+`latency`, `error`, `rate_limit`, `chaos`, whatever order you write them in,
+and the first to fail a request ends it: with `error` set, `rate_limit` and
+`chaos` never fire. Set one failure at a time, optionally with `latency`.
+
+The mock's default handler always serves, and conditions run in front of it.
+An entry with only `path` or `id`, as the Postman app writes, injects nothing.
+Unknown condition names are ignored, so a misspelled one fails silently.
+`overrides.bypass` prints a warning and is ignored.
+
+The legacy form `- type: error` with `config: { status_code: 503 }` is still
+accepted and validated strictly: an unknown `type` is an error.
+
+| Condition | Field | Effect |
+| --- | --- | --- |
+| `latency` | `delay_ms` (positive number) | Holds each request that long, then serves it normally. |
+| `error` | `status_code` (integer 400–599) | Every request returns that status with `{"error":{...},"scenario":"error"}`. |
+| `rate_limit` | `requests_per_minute` (positive integer) | Requests over the limit return `429` with a `Retry-After` header and `"scenario":"rate_limit"`. |
+| `chaos` | `failure_rate` (0–100) | That percentage of requests, chosen at random, return `500` with `"scenario":"chaos"`. |
+
+A condition applies to every route on its member. To fail one endpoint while
+its siblings succeed, split that endpoint into its own mock.
+
+## `simulation run`
+
+| Flag | Notes |
+| --- | --- |
+| `-p, --port <n\|auto>` | Port to serve on. Defaults to 3000, and silently falls back to a free port if 3000 is busy. An explicit port fails instead. |
+| `--output ndjson` | One JSON event per line on stdout, instead of the default readable log; messages go to stderr: `listening` (port, url, each member's `routeKey` and `address`); `request`, one per request a member served (`routeKey`, `method`, `path`, `statusCode`, `duration` in ms, headers and bodies); and `summary` on shutdown (`requestsServed`, `requestsFailed`). The router's own `400` and `404`, and injected faults, aren't logged. |
+| `-e`, `-g`, `--dataset` | Environment, globals and datasets for every member, as for `mock run`. |
+| `--no-history` | Record nothing. A `.sim.yaml` linked to a workspace otherwise records each start there; an unlinked one records only with `-w` and `--simulation`. |
+
+The argument can also be a simulation id from a workspace: the members are
+fetched and served locally. All members start before the port opens, so one
+`listening` event means the whole simulation is up. A member that fails to
+start stops the run with `Error: ...` and exit code 1. Ctrl+C stops everything.

package/skills/api-testing/SKILL.md

@@ -73,9 +73,10 @@ answering "did my app's actual calls conform to the contract," not "does
 this endpoint respond correctly." `--capture-only` skips the matching step
 entirely and just exports what was captured as a new v3 collection,
 organized by host — a way to bootstrap a collection from real traffic
-rather than authoring one from scratch. Results upload to Postman
-automatically after each run; `--report-events=false` skips that for a run
-that shouldn't be recorded.
+rather than authoring one from scratch. Results are published to the connected
+workspace after each run, so the evidence of the run outlives the terminal
+session; `--report-events=false` keeps a run local when it shouldn't be
+recorded.
 
 ## Critical Rules
 

package/skills/bootstrap/SKILL.md

@@ -22,8 +22,7 @@ repo is already set up.
 - Never invent a subcommand or a flag. Run `-h` first and believe it.
 - Lint specs with `postman spec lint`, never `postman api …` — the API Builder
   is deprecated in v12+ and the CLI prints no warning.
-- Local commands need no login; only commands that reach the Postman
-  workspace do. Don't force a login the task doesn't need.
+- Local commands need no login.
 - A missing `postman` binary means install it. Route to `postman-mcp-server`
   only after an install has been attempted and actually failed.
 - Never fabricate a workspace id, spec path, or collections directory. Report
@@ -31,11 +30,15 @@ repo is already set up.
 - Never echo an API key or session token into output, logs, or summaries.
 - "Present" is not "current": check the version and existing links before
   setting anything up.
-- Wire up an existing repo only. Never scaffold a new API or a starter spec.
+- Operate inside a repository, including a fresh repository for a new project.
+  Never scaffold the API implementation or a starter spec.
 - Write no host-specific paths — the same `skills/` directory loads on every
   route.
 - Do not use `init` or `workspace create` to share or import a workspace that
   already exists. Choose the direction of sync from the lifecycle table below.
+- Before pulling, apply `api-discovery`'s owning-workspace-versus-dependency
+  distinction; finding a workspace does not by itself make it this
+  repository's workspace.
 
 ## Ask the CLI: `-h`
 
@@ -79,15 +82,16 @@ npm view postman-cli version
 
 ### 1.2 Install only if missing
 
-**Preferred — npm, all platforms:**
+**npm — all platforms, using Node's global package install:**
 
 ```bash
 npm install -g postman-cli
 ```
 
-**Windows, or avoiding a global npm install:** use the platform installers in
-[reference/cli_installation.md](reference/cli_installation.md). Every route puts
-`postman` on `PATH`.
+**Platform installers — direct shell installs for macOS, Linux, WSL, and
+Windows:** use the commands in
+[reference/cli_installation.md](reference/cli_installation.md). Every route
+puts `postman` on `PATH`.
 
 **Updating a copy that already exists:** use the same route that installed it.
 curl-installed binaries don't take `npm install -g` cleanly.
@@ -101,10 +105,10 @@ only thing that qualifies.
 
 ### 2.1 Authenticate only if this step needs it
 
-Local commands need no login, and `postman init` is among them — its own help
-says *"No authentication, and safe in CI."* Skip this entirely unless the
-command you're about to run pulls or pushes an existing workspace, or shares
-one with a team.
+`postman init` needs no normal login — init uses an agent-scoped session.
+Do not log in before init. Authenticate only when the command you're about to
+run operates on an existing workspace, such as listing, inspecting, pulling,
+pushing, or changing access to one.
 
 **With an API key — preferred, non-interactive:**
 
@@ -127,23 +131,27 @@ more.
 Read `.postman/resources.yaml` for `localResources` and `workspace.id`, and
 inspect the local `postman/` tree. When the user names an existing workspace or
 asks to import, sync, or share one, use `workspace list --json` and `workspace
-get <id> --elements --json` to confirm the workspace side. Never create a
-second workspace merely because this repository is not connected yet.
-
-Prefer filesystem-first work: materialize an existing workspace with
-`workspace pull <id>`, or initialize local files with `postman init --no-cloud`
-when no workspace exists. Then inspect, edit, diff, and validate the
-version-controlled files before any push.
+get <id> --elements --json` to confirm the workspace side. Also establish
+whether that workspace owns the service represented by this repository. Never
+create a second workspace merely because this repository is not connected yet,
+and never replace this repository's binding with another service's workspace.
+
+Prefer filesystem-first work. For the current service, materialize its existing
+workspace with `workspace pull <id>`, or create and bind one with `postman init
+--json --visibility <personal|team>` when no workspace exists. For another
+service, use `postman dependency add <type> <name-or-id>` as described in
+`api-discovery`. Then inspect, edit, diff, and validate the version-controlled
+files before any push.
 
 | Existing state and intent | Use | Why |
 | --- | --- | --- |
-| No workspace exists; start locally | `postman init --json --no-cloud` | Creates the git-native filesystem without requiring login. |
-| No workspace exists; create and bind one | `postman workspace create --visibility <value>` or the explicit init creation path | Creation is the requested lifecycle event. |
-| Workspace exists; enable filesystem work | `postman workspace pull <workspace-id>` | Connects the workspace to the repository and materializes its entities under `postman/`. |
-| Workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds without downloading its contents. |
+| No workspace exists; create and bind one | `postman init --json --visibility <personal|team>` or `postman workspace create --visibility <value>` | Creates and binds the owning workspace; the init path also creates the git-native filesystem. |
+| The current service's workspace exists; enable filesystem work in its repository | `postman workspace pull <workspace-id>` | Connects the owning workspace to the repository and materializes its entities under `postman/`. |
+| The current service's workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds its repository without downloading its contents. |
+| Another service's resource is needed here | `postman dependency add <type> <name-or-id>`; add `--workspace <workspace-id>` when resolving a name in a specific workspace | Declares and downloads only that collection, environment, or mock without rebinding this repository or pulling the other service's whole workspace. |
 | Bound workspace; the workspace is authoritative | `postman workspace pull` | Refreshes local files from the connected workspace. |
-| Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Previews and publishes creates/updates without deleting unmatched workspace entities. |
-| “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Publishes local contents to the existing workspace; `create` would make a duplicate. |
+| Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Persists the local API context for future work and sharing with others by publishing creates/updates without deleting unmatched workspace entities. |
+| “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Persists local context in the existing workspace so teammates can share and build on it; `create` would make a duplicate. |
 
 If “share” also requires changing a personal workspace's visibility or team
 permissions, inspect its metadata first. `push` synchronizes entities; it does
@@ -162,15 +170,20 @@ deletions. Do not add `-y` merely to bypass a prompt.
 environments. Downstream skills read that file and nothing else.
 
 ```bash
-postman init --json --no-cloud               # local only, no workspace
-postman init --json --visibility personal    # also create and bind a workspace
+postman init --json --visibility personal
+postman init --json --visibility team
 ```
 
 Use `--visibility` only when a new workspace is actually wanted. If the
-workspace already exists, use `pull` to enable the filesystem workflow;
-use `push` only when publishing local changes to an already-bound workspace.
+current service's workspace already exists, use `pull` from that service's
+repository to enable the filesystem workflow. If the existing workspace
+belongs to another service, use it as a dependency instead. Use `push` only
+when publishing local changes to an already-bound workspace.
 
-**The workspace step is interactive** without `--no-cloud` or `--visibility`.
+Without `--visibility`, interactive init prompts for the workspace step, while
+`--json` skips that step because it may not prompt. Use `--visibility` when an
+agent should create and bind a workspace non-interactively; omit it when a
+local-only setup is intended.
 
 **Read the payload, not stderr.** Take `bindings` and `exitCode` from the JSON.
 Each binding reports a `source` of `inferred` or `none` — an inferred spec is a
@@ -187,8 +200,9 @@ written but the requested workspace was not created — it does *not* mean re-ru
 - `postman --version` returned a real version.
 - Auth is confirmed, or established as not required for this task.
 - `.postman/resources.yaml` names a spec or a collections directory.
-- `workspace.id` is set, or the run was deliberately local-only — `--no-cloud`
-  leaves it empty and still exits 0, which is a pass, not a gap.
+- When workspace creation was requested or the repository was already bound,
+  `workspace.id` is set to the owning workspace. A deliberately local-only
+  init may omit it.
 - After `pull`, expected workspace entities exist under `postman/`. After
   `push`, report created/updated entities and conflicts; do not claim a
   workspace is shared unless its access level permits the intended teammates.
@@ -201,7 +215,7 @@ written but the requested workspace was not created — it does *not* mean re-ru
 ## Postman bootstrap
 - **CLI**: <version> (latest: <version> | not checked)
 - **Auth**: <api-key | browser | not required for this task>
-- **Workspace**: <id | none — local only>
+- **Workspace**: <id | not requested | creation failed: reason>
 - **Spec path**: <path (inferred | explicit) | none — user must create>
 - **Collections dir**: <path | none — user must create>
 ```

package/skills/bootstrap/reference/cli_installation.md

@@ -1,8 +1,9 @@
 # Postman CLI Installation
 
-A global install, on `PATH`, installed by one of three tools depending on
-platform. Whichever one put the binary there is the one to use again when
-updating it — mixing tools leaves two `postman` binaries and a `PATH`
+A global install on `PATH`. npm works anywhere Node is available; the curl
+installer covers macOS, Linux, and WSL; and the PowerShell installer covers
+Windows. Whichever route put the binary there is the one to use again when
+updating it — mixing routes leaves two `postman` binaries and a `PATH`
 question.
 
 ## Install

package/skills/ci-integration/SKILL.md

@@ -37,15 +37,16 @@ answers it (and covers every collection in the repo in one pass); reach for
 bare `collection lint` only when there's no workspace to fetch rules from
 yet.
 
-## Push to workspace — only after merge
-
-`postman workspace push -y` is the one command in this skill that changes
-shared cloud state, so it belongs behind a merge-to-main trigger, not a PR
-trigger. `-y` skips confirmation prompts a non-interactive job can't answer.
-Leave `--no-prepare` off — the default prepare step is what assigns real IDs
-to entities that are new since the last push; skipping it because a run
-felt slow trades a few seconds for a push that silently fails to create
-anything new.
+## Persist and share context — only after merge
+
+`postman workspace push -y` persists the merged repository's API context in
+the workspace for future work and enables sharing it with others. It is the one
+command in this skill that changes shared workspace state, so it belongs behind
+a merge-to-main trigger, not a PR trigger. `-y` skips confirmation prompts a
+non-interactive job can't answer. Leave `--no-prepare` off — the default
+prepare step is what assigns real IDs to entities that are new since the last
+push; skipping it because a run felt slow trades a few seconds for a push that
+silently fails to create anything new.
 
 `--push-strategy force-sync` mirrors the whole workspace, deleting any cloud
 entity with no local counterpart — genuinely destructive, and not the

package/skills/datasets/SKILL.md

@@ -40,11 +40,12 @@ dataset: `list` takes a path or directory (its cloud form is
 neither — it reads a driver JAR and touches no dataset at all.
 
 There is no `dataset push` verb — but that does not mean local and cloud are
-sealed off from each other. Datasets are a workspace entity, so
-`postman workspace push` syncs them to the bound workspace along with
-collections, environments and the rest, and `postman workspace pull` brings
-them back down. Reach for those when the whole repo should move; the
-`dataset` verbs below are for working on one dataset in place.
+sealed off from each other. Datasets are a workspace entity, so `postman
+workspace push` persists them in the bound workspace alongside collections,
+environments and the rest, making that context available to future work and
+for sharing with others. `postman workspace pull` brings them back down. Reach
+for those when the whole repo should move; the `dataset` verbs below are for
+working on one dataset in place.
 
 ## Core knowledge
 

package/skills/flows/reference/flow_cli_flags.md

@@ -80,7 +80,7 @@ execution and reporting. Takes the path positionally; a bad path fails with
 | `-x, --suppress-exit-code` | Overrides the run's exit code. Defeats CI gating. |
 | `--verbose` | Per-request detail: method, URL, assertions. |
 | `--no-truncate` | Full output, no truncated long values. |
-| `--no-report-events` | Don't send analytics. `--report-events` exists for compatibility; analytics are on by default. |
+| `--no-report-events` | Keep the run local instead of publishing results to the connected workspace. |
 
 ### BETA: dataset iteration
 

package/skills/variables/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: variables
+description: How to parameterize a collection with variables and where each value belongs — a plain value goes in an environment or collection variable, a secret (token, password, API key) goes in the team's shared vault via `postman secret create` so its value never passes through the coding harness or lands in a committed file. Covers the variable scopes and their resolution order, reading and writing variables at runtime from pre-request and post-response scripts (`pm.environment`, `pm.collectionVariables`, `pm.variables`), and composing variables out of other variables. Use when the user asks where to put a base URL, token, or password, how to reference a secret without exposing it, how `{{variables}}` resolve, or how to set a value in a script. Covers `postman secret`.
+---
+
+# Variables
+
+A variable lets a request name a value — `{{base_url}}`, `{{authToken}}` —
+instead of hardcoding it, so one collection runs against staging and
+production and a secret never has to be typed into a request. The only real
+decision is **where the value lives**, and it turns on one question: is it a
+secret?
+
+## Core foundations
+1. One collection, many targets. Parameterize everything that changes between
+   environments so the same requests run everywhere — a diff in values, not in
+   requests.
+2. Where a value lives is a security decision, not a convenience one. A plain
+   value is a variable; a secret belongs in the vault, nowhere else.
+3. A secret's value should never reach this harness, the terminal, or a
+   committed file. `type: secret` only hides it in the UI — the value still
+   sits in clear text in the YAML. The vault is the only place it stays out of
+   the repo. (ref: postman secret command) 
+4. Resolution is narrowest-wins: `local (script) > data (iteration row) >
+   environment > collection > global`. This is what lets a collection ship a
+   default and an environment override just the few that differ.
+5. Variables compose. A value can reference another (`usersUrl =
+   {{base_url}}/users`), and a script can set one at runtime to chain requests
+   (capture a token, use it on the next call). Resolution happens at send
+   time, not at definition time.
+
+## Non-secret variables
+
+A base URL, a non-sensitive id, a feature flag, a default page size — store it
+as a variable and commit it. Reference it as `{{key}}` in a URL, header, query
+param, or body. Scope picks the file:
+
+- **Collection variable** — travels with the collection; use it for a default
+  that belongs to the API itself and rarely changes.
+- **Environment variable** — swapped per target; use it for anything that
+  differs between staging and production. One file per environment, selected
+  at run time.
+
+
+You can either directly edit into collection / environment file or use the cli commands to achieve the same.
+```bash
+postman environment new "Staging"
+postman environment var set base_url https://staging.example.com \
+  --environment "postman/environments/Staging.environment.yaml"
+postman environment lint postman/environments --fail-severity warning
+```
+
+Set one at runtime from a script when you need to chain requests:
+
+```javascript
+// post-response: capture for later requests
+pm.environment.set("authToken", pm.response.json().access_token);
+// pre-request: read it back (any scope, resolution order applies)
+const base = pm.variables.get("base_url");
+```
+
+Use `pm.environment`/`pm.collectionVariables` to target a scope, `pm.variables`
+to read across all of them, and `pm.variables.set` for a local value that
+lives only for the current run.
+
+## Secret keys
+
+Passport is how people, services, and agents call APIs without ever holding
+the secret. `postman secret` is the vault side of the same idea: it stores and
+links secrets without putting their values in agent context or repository
+files. Run `postman secret -h` for the supported vault operations and flags.
+
+A bearer token, password, API key, client secret, or signing key goes in the
+team's **shared vault**:
+
+```bash
+# interactive masked prompt (default when stdin is a terminal)
+postman secret create STRIPE_API_KEY --workspace <workspaceId>
+```
+By default only the creator of secret can view the secret. Others in workspace can resolve the secret in their runs but can not see the secret value.
+
+You then link the secret to an environment variable to use it in a request —
+the CLI writes the link for you from `secret create`'s output:
+
+```bash
+postman environment var set api_key --secret-id <secret-id> --vault-id <vault-id> \
+  --environment "postman/environments/Staging.environment.yaml"
+```
+
+The variable now points at the vault instead of holding a value; the file
+carries only the reference, never the secret:
+
+```yaml
+values:
+  - key: api_key
+    enabled: true
+    type: secret
+    description: API key
+    secret: true
+    source:
+      provider: postman
+      postman:
+        type: cloud
+        secretId: <secret-id>
+        vaultId: <vault-id>
+```