postman-cli 1.62.0 → 1.65.0

package/README.md

@@ -20,6 +20,18 @@ The Postman CLI brings the power of Postman’s API platform directly to your te
 npm install -g postman-cli
 ```
 
+After a global npm installation, the package checks for existing Claude Code and Codex
+configuration directories. When found, it adds a managed Postman CLI availability note to
+the agent's global instructions without replacing existing content. This step is idempotent
+and non-blocking, so an inaccessible agent configuration does not fail the CLI installation.
+
+npm hides successful lifecycle-script output by default. To see the agent configuration
+summary and Claude Code plugin recommendation during installation, use:
+
+```bash
+npm install -g postman-cli --foreground-scripts
+```
+
 ### Alternative Installation Methods
 
 For direct binary downloads, platform-specific installers, or other installation methods, see the **[Installation Guide](https://learning.postman.com/docs/postman-cli/postman-cli-installation/)**.

package/bin/postman.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+const { constants } = require('os');
+
 // Keep this wrapper alive while the native binary handles shutdown gracefully.
 process.on('SIGINT', function () {});
 process.on('SIGTERM', function () {});
@@ -10,5 +12,22 @@ try {
     run(...process.argv.slice(2));
 }
 catch (error) {
+    // The CLI's exit codes are a documented contract (`postman init` returns 2 for
+    // ambiguous specs and 4 for a refusal, for instance), so the binary's own code has
+    // to survive this wrapper. execFileSync throws on any non-zero exit and carries
+    // the code as `status`; collapsing that to 1 made a recoverable refusal
+    // indistinguishable from a crash.
+    if (typeof error.status === 'number') {
+        process.exit(error.status);
+    }
+
+    // A signalled child has no status. Report it the way a shell does.
+    if (error.signal) {
+        process.exit(128 + (constants.signals[error.signal] || 0));
+    }
+
+    // Spawning the binary failed outright (missing platform package, not executable).
+    // The message never reached the user before, leaving a silent exit 1.
+    process.stderr.write(`${error.message || error}\n`);
     process.exit(1);
 }

package/man/postman.1

@@ -1,4 +1,4 @@
-.TH POSTMAN 1 "2026-09-22" "v1.62.0" "Postman CLI Manual"
+.TH POSTMAN 1 "2026-09-25" "v1.65.0" "Postman CLI Manual"
 .SH NAME
 postman \- Command\-line companion utility for Postman
 .SH SYNOPSIS
@@ -94,7 +94,7 @@ Use the skills bundled with this CLI instead of fetching the latest
 Which spec is authoritative, when more than one could be
 .TP
 .B \-\-visibility <status>
-Create and bind a workspace non\-interactively (personal or team)
+Create and bind a workspace non\-interactively (personal, team)
 .TP
 .B \-\-no\-cloud
 Skip the workspace step entirely
@@ -120,11 +120,21 @@ Exit codes:
 
 Code 5 needs \-\-visibility: without it no workspace was requested, so nothing
 can fail for not getting one. It does not mean re\-run init \- the local files
-are already written.
-
-Under \-\-json, read `exitCode` and `refusal` from the payload rather than
-matching the messages on stderr. `refusal.kind` is one of
-foreign\-postman\-dir, bound\-spec\-missing, spec\-hint\-unmatched.
+are already written. A \-\-visibility that is not personal, team is code 5 on
+every path, including \-\-json, CI and \-\-no\-cloud: none of them makes the value
+usable, so none of them should report success for it.
+
+Under \-\-json, read `exitCode`, `refusal`, `usageError` and `cloud` from the
+payload rather than matching the messages on stderr. `refusal.kind` is one of
+foreign\-postman\-dir, bound\-spec\-missing, spec\-hint\-unmatched. `usageError`
+names the flag whose value init could not use. `cloud` says what happened to
+the workspace step, including why it was skipped.
+
+\-\-json with \-\-visibility creates the workspace, same as without it: stdout
+carries the payload and everything meant for a person goes to stderr. It used
+to skip the step and exit 0, so a missing `origin` remote or a failed bind
+went unreported. Without \-\-visibility, \-\-json still skips \- there is nothing
+to create and init may not prompt.
 
 Examples:
   $ postman init
@@ -283,9 +293,18 @@ Score a Postman collection for AI readiness by ID, local file path, or local\-mo
 .B collection get
 Fetch a Postman collection in the V3 format and print it.
 .TP
+.B collection generate
+Generate artifacts from a collection.
+.TP
+.B collection sync
+Sync artifacts generated from a collection.
+.TP
 .B collection request
 Add, update, or remove requests in a local v3 collection.
 .TP
+.B collection folder
+Add, update, or remove folders in a local v3 collection.
+.TP
 .B collection list
 List collections: your local project's collections by default, or a Postman cloud workspace's collections with \-\-workspace.
 .TP
@@ -363,6 +382,9 @@ Score a Postman collection for AI readiness by ID, local file path, or local\-mo
 .B \-o, \-\-output <value>
 Output format for the results. [choices: "cli", "json", "html"]
 .TP
+.B \-\-export <path>
+Write the report to this file instead of stdout. A directory receives the report under a name derived from the collection. Requires \-\-output html.
+.TP
 .B \-\-min\-score <n>
 Exit with a non\-zero code if the overall score is below this threshold (0\-100).
 
@@ -372,6 +394,7 @@ Examples:
   $ postman collection ai\-readiness ./postman/collections/My\e API
   $ postman collection ai\-readiness ./my\-collection.json
   $ postman collection ai\-readiness 631643\-f695cab7\-... \-\-output json
+  $ postman collection ai\-readiness ./my\-collection.json \-\-output html > report.html
   $ postman collection ai\-readiness ./my\-collection.json \-\-min\-score 70
 
 Resolving a collection by ID requires authentication. Use `postman login` before running this command with a UID.
@@ -397,6 +420,80 @@ Eg. postman collection get 12345\-33823532ab9e41c9b6fd12d0fd459b8b
     postman collection get 0123456789abcdef01234567 \-\-json
 
 
+.SS "collection generate"
+Generate artifacts from a collection.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B collection generate spec
+Generate an OpenAPI specification from a Postman collection.
+
+.SS "collection generate spec"
+Generate an OpenAPI specification from a Postman collection.
+
+.B Usage:
+[options] <collection>
+
+.B Options:
+.TP
+.B \-n, \-\-name <name>
+Specification name / title
+.TP
+.B \-\-spec\-version <ver>
+Target OpenAPI version: 3.1, 3.0, or 2.0 (default: 3.1) (default: 3.1)
+.TP
+.B \-f, \-\-format <fmt>
+Output format: yaml or json (default: yaml) (default: yaml)
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman collection generate spec ./postman/collections/My\e API \-n "My API Spec"
+  postman collection generate spec ./postman/collections/My\e API \-n "My Spec" \-\-spec\-version 3.0
+  postman collection generate spec ./collection.json \-n "My Spec" \-f json
+  postman collection generate spec 12345678\-abcd\-1234\-abcd\-1234567890ab \-n "My Spec"
+
+
+
+.SS "collection sync"
+Sync artifacts generated from a collection.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B collection sync spec
+Sync a specification from a linked collection (local path or cloud UUID).
+
+.SS "collection sync spec"
+Sync a specification from a linked collection (local path or cloud UUID).
+
+.B Usage:
+[options] <collection>
+
+.B Options:
+.TP
+.B \-\-spec\-id <id>
+Specification ID to sync (required for cloud mode)
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman collection sync spec ./postman/collections/My\e API
+  postman collection sync spec 12345\-col\-id \-\-spec\-id 67890\-spec\-id
+
+
+
 .SS "collection request"
 Add, update, or remove requests in a local v3 collection.
 
@@ -547,6 +644,132 @@ Examples:
 
 
 
+.SS "collection folder"
+Add, update, or remove folders in a local v3 collection.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B collection folder add
+Add an empty folder to a local v3 collection (set its details later with `update`).
+.TP
+.B collection folder update
+Update a folder in a v3 collection (only the fields you pass).
+.TP
+.B collection folder rm
+Remove a folder from a v3 collection (recursive: removes everything inside it).
+
+.SS "collection folder add"
+Add an empty folder to a local v3 collection (set its details later with `update`).
+
+.B Usage:
+[options] [folder\-name]
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection: name, directory, id, cloud id, or path. Required.
+.TP
+.B \-\-folder <id|name|path>
+Parent folder within the collection, e.g. "Users/Admin". Defaults to the root.
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-json
+JSON output.
+
+.TP Examples:
+
+Creates an empty folder (name only); set its description with `collection folder update`. Nest it with \-\-folder.
+
+Examples:
+  postman collection folder add Users \-\-collection "My API"
+  postman collection folder add \-\-collection "My API"            # named "New folder"
+  postman collection folder add Admin \-\-collection "My API" \-\-folder Users
+
+
+
+.SS "collection folder update"
+Update a folder in a v3 collection (only the fields you pass).
+
+.B Usage:
+[options] <folder>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection: name, directory, id, cloud id, or path (cloud: id only). Required.
+.TP
+.B \-\-folder <id|name|path>
+Parent folder to scope the selector, e.g. "Users" (local: name/path; cloud: id).
+.TP
+.B \-\-name <name>
+Rename the folder (moves its directory).
+.TP
+.B \-\-description <text>
+Folder description.
+.TP
+.B \-\-auth <spec>
+Folder auth: none, inherit, bearer:TOKEN, basic:USER:PASS, apikey:KEY:VALUE[:header|query], oauth2:TOKEN.
+.TP
+.B \-\-scripts <event:script>
+Replace folder scripts. event is prerequest or test; script is @file, \- for stdin, or inline. Repeatable. (default: )
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-json
+JSON output.
+
+.TP Examples:
+
+Select the folder by the <folder> selector: local — a name or "Parent/Name" path (or \-\-folder to scope a bare name); cloud (\-\-workspace) — a folder id, with \-\-collection an id too.
+
+Examples:
+  postman collection folder update Users \-\-collection "My API" \-\-name Accounts
+  postman collection folder update "Users/Admin" \-\-collection "My API" \-\-description "Admin endpoints"
+  postman collection folder update Admin \-\-collection "My API" \-\-folder Users \-\-auth bearer:TOKEN
+  postman collection folder update <folderId> \-\-collection <collectionId> \-\-name Accounts \-w <workspaceId>
+
+
+
+.SS "collection folder rm"
+Remove a folder from a v3 collection (recursive: removes everything inside it).
+
+.B Usage:
+[options] <folder>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection: name, directory, id, cloud id, or path (cloud: id only). Required.
+.TP
+.B \-\-folder <id|name|path>
+Parent folder to scope the selector, e.g. "Users" (local: name/path; cloud: id).
+.TP
+.B \-y, \-\-yes
+Skip the confirmation prompt (required when stdout is not a TTY).
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-json
+JSON output.
+
+.TP Examples:
+
+Removal is recursive. Select the folder by the <folder> selector: local — a name or "Parent/Name" path (or \-\-folder to scope a bare name); cloud (\-\-workspace) — a folder id, with \-\-collection an id too.
+
+Examples:
+  postman collection folder rm Users \-\-collection "My API" \-\-yes
+  postman collection folder rm "Users/Admin" \-\-collection "My API" \-y
+  postman collection folder rm <folderId> \-\-collection <collectionId> \-y \-w <workspaceId>
+
+
+
 .SS "collection list"
 List collections: your local project's collections by default, or a Postman cloud workspace's collections with \-\-workspace.
 
@@ -733,6 +956,15 @@ Redirect requests for a URL or {{variable}} to a mock during the run. Format: "<
 .B \-\-simulate <path>
 Start mock servers with fault\-injection scenarios from a .sim.yaml file
 .TP
+.B \-\-simulation <id>
+Simulation id to record start history against when using \-\-simulate.
+.TP
+.B \-\-simulate\-workspace <id>
+Workspace that owns the \-\-simulate run, for recording its start history.
+.TP
+.B \-\-no\-simulate\-history
+Do not record the \-\-simulate run in the simulation's start history.
+.TP
 .B \-\-report\-events
 Upload results for git\-native v3 collection runs. Analytics are sent by default
 .TP
@@ -1211,6 +1443,9 @@ Create a new spec in a workspace, or (with path) scaffold a local spec file.
 .TP
 .B spec generate
 Generate artifacts from a specification.
+.TP
+.B spec sync
+Sync a generated collection with its source specification.
 
 .SS "spec lint"
 Run linting on the given specification by ID or local file path.
@@ -1248,6 +1483,9 @@ Score an OpenAPI specification for AI readiness by ID or local file path.
 .B \-o, \-\-output <value>
 Output format for the results. [choices: "cli", "json", "html"]
 .TP
+.B \-\-export <path>
+Write the report to this file instead of stdout. A directory receives the report under a name derived from the specification. Requires \-\-output html.
+.TP
 .B \-\-min\-score <n>
 Exit with a non\-zero code if the overall score is below this threshold (0\-100).
 
@@ -1256,6 +1494,8 @@ Exit with a non\-zero code if the overall score is below this threshold (0\-100)
 Examples:
   $ postman spec ai\-readiness ./openapi.yaml
   $ postman spec ai\-readiness 6e2e5b3e\-...  \-\-output json
+  $ postman spec ai\-readiness ./openapi.yaml \-\-output html > report.html
+  $ postman spec ai\-readiness ./openapi.yaml \-\-output html \-\-export ./report.html
   $ postman spec ai\-readiness ./openapi.yaml \-\-min\-score 70
 
 
@@ -1478,6 +1718,39 @@ Examples:
 
 
 
+.SS "spec sync"
+Sync a generated collection with its source specification.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B spec sync collection
+Sync a collection from a linked specification (local path or cloud UUID).
+
+.SS "spec sync collection"
+Sync a collection from a linked specification (local path or cloud UUID).
+
+.B Usage:
+[options] <spec>
+
+.B Options:
+.TP
+.B \-\-collection\-id <id>
+Collection ID to sync (required for cloud mode)
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman spec sync collection ./postman/specs/My\e API/index.yaml
+  postman spec sync collection 12345\-spec\-id \-\-collection\-id 67890\-col\-id
+
+
+
 .SS "monitor"
 Run and manage Postman monitors.
 
@@ -2000,12 +2273,18 @@ Read a workspace's metadata, and optionally the ids of what it holds.
 .B workspace create
 Create a Postman workspace and bind it to this git repository.
 .TP
+.B workspace delete
+Permanently delete a workspace and everything in it. Prompts for confirmation unless \-\-yes is passed.
+.TP
 .B workspace pull
 Pull workspace entities from a Postman workspace into the local git\-native folder.
 .TP
 .B workspace connect-git
 Connect a Postman workspace to a local git repository.
 .TP
+.B workspace disconnect-git
+Disconnect a Postman workspace from its local git repository.
+.TP
 .B workspace diff
 Preview local\-vs\-cloud drift before pushing. Read\-only: nothing is created, updated or deleted.
 
@@ -2164,7 +2443,8 @@ Create even when a workspace is already recorded for this repo
 
 .TP Examples:
 
-Requires a login (`postman login`) or POSTMAN_API_KEY.
+Requires a login (`postman login`) or POSTMAN_API_KEY. A guest session
+has no account to own a workspace: run `postman signup` first.
 Refuses to run on CI: create once locally and commit the binding.
 
 Examples:
@@ -2175,6 +2455,38 @@ Examples:
   $ postman workspace create \-\-visibility personal \-\-no\-connect
 
 
+.SS "workspace delete"
+Permanently delete a workspace and everything in it. Prompts for confirmation unless \-\-yes is passed.
+
+.B Usage:
+[options] [workspaceId]
+
+.B Options:
+.TP
+.B \-y, \-\-yes
+Skip the confirmation prompt
+.TP
+.B \-\-json
+Print the outcome as machine\-readable JSON
+.TP
+.B \-\-verbose
+Show detailed logging
+.TP
+.B \-\-timeout <ms>
+Abort the run after this many milliseconds. Defaults to 30000.
+
+.TP Examples:
+
+Examples:
+  postman workspace delete 12345678\-90ab\-cdef\-1234\-567890abcdef
+      Confirm, then delete
+  postman workspace delete 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-yes
+      Delete without confirmation (for scripts and CI)
+  postman workspace delete 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-yes \-\-json
+      Machine\-readable outcome
+
+
+
 .SS "workspace pull"
 Pull workspace entities from a Postman workspace into the local git\-native folder.
 
@@ -2228,6 +2540,36 @@ Examples:
 
 
 
+.SS "workspace disconnect\-git"
+Disconnect a Postman workspace from its local git repository.
+
+.B Usage:
+[options] [workspaceId]
+
+.B Options:
+.TP
+.B \-y, \-\-yes
+Skip all confirmation prompts
+.TP
+.B \-\-verbose
+Show detailed logging
+
+.TP Examples:
+
+Examples:
+  postman workspace disconnect\-git
+      Disconnect the workspace this folder is connected to. Disconnects it in
+      Postman and clears the connection in .postman/resources.yaml. No files
+      are deleted.
+  postman workspace disconnect\-git <workspaceId>
+      Disconnect a specific workspace, whatever workspace this folder is
+      connected to. Use this to clear an existing workspace connection. No files
+      are deleted.
+  postman workspace disconnect\-git \-\-yes
+      CI: skip the confirmation prompt.
+
+
+
 .SS "workspace diff"
 Preview local\-vs\-cloud drift before pushing. Read\-only: nothing is created, updated or deleted.
 
@@ -2246,7 +2588,7 @@ Skip content comparison. Faster, but updates are listed without checking whether
 Print the diff as machine\-readable JSON.
 .TP
 .B \-\-exit\-code
-Exit with code 1 when drift is found (for CI gates).
+Exit with code 1 when a verified difference is found (for CI gates). Entity types with no comparison path are reported but do not fail the gate.
 .TP
 .B \-\-verbose
 Show detailed logging
@@ -2349,10 +2691,10 @@ Specify an Id to a Postman Environment
 Specify an Id to a Postman Globals
 .TP
 .B \-\-setup\-collection <id>
-Collection UID to run before the Postman Cloud performance test
+Collection UID to run before the performance test
 .TP
 .B \-\-teardown\-collection <id>
-Collection UID to run after the Postman Cloud performance test
+Collection UID to run after the performance test
 .TP
 .B \-\-vu\-count <count>
 Number of virtual users (default: 20)
@@ -2366,6 +2708,24 @@ Load profile type: fixed, ramp\-up, spike, peak (default: ramp\-up)
 .B \-\-data\-file <path>
 Path to a JSON or CSV data file to use with the collection
 .TP
+.B \-\-ssl\-client\-cert\-list <path>
+Path to a client certificates configuration file (JSON). Local runner only.
+.TP
+.B \-\-ssl\-client\-cert <path>
+Path to a client certificate (PEM) for mTLS targets. Local runner only.
+.TP
+.B \-\-ssl\-client\-key <path>
+Path to the client certificate private key. Local runner only.
+.TP
+.B \-\-ssl\-client\-passphrase <passphrase>
+Client certificate passphrase (for a protected key). Local runner only.
+.TP
+.B \-k, \-\-insecure
+Disable SSL certificate verification for the target. Local runner only.
+.TP
+.B \-\-ssl\-extra\-ca\-certs <path>
+Path to additionally trusted CA certificates (PEM) for the target. Local runner only.
+.TP
 .B \-\-dataset\-id <id>
 Use a Postman Dataset as iteration data (with \-\-dataset\-view\-id)
 .TP
@@ -2399,6 +2759,7 @@ Format: "<{{var}}|host> mock|mock\-server:<path|id> [scenario]" (default: )
 Examples:
   postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-vu\-count 50 \-\-duration 15
   postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-pass\-if "less_than(p95, 500)"
+  postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-runner local \-\-setup\-collection 123456\-11111111\-1111\-4111\-8111\-111111111111 \-\-teardown\-collection 123456\-22222222\-2222\-4222\-8222\-222222222222
   postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-runner postman\-cloud \-\-setup\-collection 123456\-11111111\-1111\-4111\-8111\-111111111111 \-\-teardown\-collection 123456\-22222222\-2222\-4222\-8222\-222222222222
   postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-runner postman\-cloud\-static\-ip
 
@@ -3563,7 +3924,7 @@ Start a mock using its path if it lives in your repository, or its id if it live
 .B Options:
 .TP
 .B \-e, \-\-environment <path>
-Path to a file of environment variables for the mock. Relative or absolute, e.g. ./postman/environments/dev.json
+Path to a file of environment variables for the mock. Relative or absolute, e.g. ./postman/environments/dev.environment.yaml
 .TP
 .B \-g, \-\-globals <path>
 Path to a file of global variables for the mock. Relative or absolute, e.g. ./globals.json
@@ -3573,14 +3934,27 @@ Port to run on (e.g. 4010), or "auto" for a free one. Defaults to the mock's con
 .TP
 .B \-\-api\-key <key>
 Postman API key, used with a Postman cloud id (defaults to your `postman login` session)
+.TP
+.B \-w, \-\-workspace <id>
+Workspace that owns the run, for recording its start history. Auto\-resolved for a Postman cloud id; required to record history for a path.
+.TP
+.B \-\-no\-history
+Do not record this run in the mock's start history.
 
 .TP Examples:
 
 Eg. postman mock run 12345678\-90ab\-cdef\-1234\-567890abcdef  # by id, from Postman cloud
     postman mock run ./postman/mocks/orders                # by path, from your repository
-    postman mock run ./postman/mocks/orders \-\-environment ./postman/environments/dev.json
+    postman mock run ./postman/mocks/orders \-\-environment ./postman/environments/dev.environment.yaml
     postman mock run ./postman/mocks/orders \-\-port auto    # pick any free port
     postman mock run ./postman/mocks/orders \-\-port 4600    # use port 4600 (fails if it is in use)
+    postman mock run ./postman/mocks/orders \-\-workspace <id>  # record start history for a path run
+
+Eligible runs are recorded in the mock's start history (source: cli) so they appear under
+"Previous starts" in Postman. Cloud ids record automatically; a manifest\-backed path run needs
+\-\-workspace. A raw handler with no mock id cannot be attributed and is not recorded.
+In CI the pipeline/branch is captured automatically. Best\-effort and never blocks the server;
+use \-\-no\-history to opt out.
 
 Paths can be relative (e.g. ./postman/mocks/orders) or absolute (e.g. /Users/me/postman/mocks/orders).
 
@@ -3943,6 +4317,28 @@ Start mocks with fault\-injection scenarios defined in a .sim.yaml file
 .B Usage:
 [options] <filepath>
 
+.B Options:
+.TP
+.B \-w, \-\-workspace <id>
+Workspace that owns the run, for recording its simulation start history.
+.TP
+.B \-\-simulation <id>
+Simulation id to record start history against (a local .sim.yaml has only a name). Required, with \-\-workspace, to record history.
+.TP
+.B \-\-api\-key <key>
+Postman API key for recording start history (defaults to your `postman login` session).
+.TP
+.B \-\-no\-history
+Do not record this run in the simulation's start history.
+
+.TP Examples:
+
+Eligible runs are recorded in the simulation's start history (source: cli) so they appear
+under "Previous starts" in Postman. A parent start is recorded with one child start per member
+mock; pass \-\-workspace and \-\-simulation to enable it. In CI the pipeline/branch is captured
+automatically. Best\-effort and never blocks the servers; use \-\-no\-history to opt out.
+
+
 .SS "describe"
 [Beta] Get API context for AI coding agents directly from the command line.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postman-cli",
-  "version": "1.62.0",
+  "version": "1.65.0",
   "description": "Official Postman CLI - Command-line companion for API development, testing, and automation",
   "keywords": [
     "postman",
@@ -49,19 +49,23 @@
   "bin": {
     "postman": "bin/postman.js"
   },
+  "scripts": {
+    "postinstall": "node ./scripts/post-npm-installation.js"
+  },
   "man": "./man/postman.1",
   "files": [
     "bin/",
     "index.js",
     "package.json",
     "README.md",
-    "man/"
+    "man/",
+    "scripts/"
   ],
   "optionalDependencies": {
-    "@postman/pm-bin-macos-arm64": "1.62.0",
-    "@postman/pm-bin-macos-x64": "1.62.0",
-    "@postman/pm-bin-linux-x64": "1.62.0",
-    "@postman/pm-bin-linux-arm64": "1.62.0",
-    "@postman/pm-bin-windows-x64": "1.62.0"
+    "@postman/pm-bin-macos-arm64": "1.65.0",
+    "@postman/pm-bin-macos-x64": "1.65.0",
+    "@postman/pm-bin-linux-x64": "1.65.0",
+    "@postman/pm-bin-linux-arm64": "1.65.0",
+    "@postman/pm-bin-windows-x64": "1.65.0"
   }
 }

package/scripts/post-npm-installation.js

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console */
+/* eslint-disable one-var */
+
+const fileSystem = require('node:fs');
+const operatingSystem = require('node:os');
+const path = require('node:path');
+
+const POSTMAN_INSTRUCTION =
+        'Postman CLI is installed on this device, and can be used for API Engineering work.',
+    POSTMAN_INSTRUCTION_START = '<!-- postman-cli:installation:start -->',
+    POSTMAN_INSTRUCTION_END = '<!-- postman-cli:installation:end -->',
+    POSTMAN_INSTRUCTION_BLOCK = [
+        POSTMAN_INSTRUCTION_START,
+        POSTMAN_INSTRUCTION,
+        POSTMAN_INSTRUCTION_END
+    ].join('\n'),
+    CLAUDE_PLUGIN_MESSAGE = [
+        '',
+        'Claude Code users and agents can use the Postman Plugin for Claude Code for full API lifecycle',
+        'management including documentation, collections, workspaces, environments, mocks, monitors right',
+        'from your repository.',
+        '',
+        'Install it with:',
+        '  claude plugin install postman@claude-plugins-official',
+        '',
+        'Then start Claude Code and run:',
+        '  /postman:setup'
+    ].join('\n');
+
+/**
+ * @typedef {Object} AgentConfiguration
+ * @property {string} name - User-facing agent name.
+ * @property {string} configurationEnvironmentVariable - Environment override for the configuration root.
+ * @property {string} fallbackDirectory - Directory beneath the current user's home directory.
+ * @property {string[]} instructionFileNames - Ordered instruction files; the last is the fallback.
+ * @property {(context: AgentPostConfigurationContext) => void} [postConfiguration] - Agent follow-up.
+ */
+
+/**
+ * Selects the first existing instruction file, or the final configured fallback.
+ *
+ * @param {AgentConfiguration} agentConfiguration - Agent path conventions.
+ * @param {string} configurationRoot - Resolved agent configuration root.
+ * @returns {string} Absolute instruction-file path.
+ */
+function resolveInstructionFile (agentConfiguration, configurationRoot) {
+    const existingInstructionFileName = agentConfiguration.instructionFileNames.find(
+        (instructionFileName) => {
+            return fileSystem.existsSync(path.join(configurationRoot, instructionFileName));
+        }
+    );
+
+    return path.join(
+        configurationRoot,
+        existingInstructionFileName || agentConfiguration.instructionFileNames[
+            agentConfiguration.instructionFileNames.length - 1
+        ]
+    );
+}
+
+/** @type {AgentConfiguration[]} */
+const AGENT_CONFIGURATIONS = [
+    {
+        name: 'Claude Code',
+        configurationEnvironmentVariable: 'CLAUDE_CONFIG_DIR',
+        fallbackDirectory: '.claude',
+        instructionFileNames: ['CLAUDE.md'],
+        postConfiguration: ({ configurationResult, invocationDirectory }) => {
+            const projectConfigurationDetected = invocationDirectory ?
+                isDirectory(path.join(invocationDirectory, '.claude')) :
+                false;
+
+            if (configurationResult.detected || projectConfigurationDetected) {
+                console.log(CLAUDE_PLUGIN_MESSAGE);
+            }
+        }
+    },
+    {
+        name: 'Codex',
+        configurationEnvironmentVariable: 'CODEX_HOME',
+        fallbackDirectory: '.codex',
+        instructionFileNames: ['AGENTS.override.md', 'AGENTS.md']
+    }
+];
+
+/**
+ * @param {NodeJS.ProcessEnv} environment - Installation environment.
+ * @returns {boolean} Whether npm is installing the package globally.
+ */
+function isGlobalInstallation (environment) {
+    const globalSetting = String(environment.npm_config_global || '').toLowerCase();
+
+    return globalSetting === 'true' || globalSetting === '1';
+}
+
+/**
+ * @param {string} directory - Directory to inspect.
+ * @returns {boolean} Whether the path is an accessible directory.
+ */
+function isDirectory (directory) {
+    try {
+        return fileSystem.statSync(directory).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+
+/**
+ * @param {unknown} error - Caught failure.
+ * @returns {string} Sanitized failure classification.
+ */
+function getErrorCode (error) {
+    try {
+        return error && typeof error.code === 'string' ? error.code : 'UNKNOWN';
+    }
+    catch {
+        return 'UNKNOWN';
+    }
+}
+
+/**
+ * Reporting must not turn this best-effort hook into a failed npm installation.
+ *
+ * @param {string} message - Sanitized warning to print.
+ * @returns {void}
+ */
+function printNonBlockingWarning (message) {
+    try {
+        console.warn(message);
+    }
+    catch {
+        // The post-install configuration remains non-critical when output is unavailable.
+    }
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} environment - Installation environment.
+ * @param {string} userHome - Current user's home directory.
+ * @returns {string|null} Directory from which the user invoked npm.
+ */
+function resolveInvocationDirectory (environment, userHome) {
+    const initialDirectory = environment.INIT_CWD && environment.INIT_CWD.trim();
+
+    return initialDirectory ? path.resolve(userHome, initialDirectory) : null;
+}
+
+/**
+ * @param {AgentConfiguration} agentConfiguration - Agent path conventions.
+ * @param {NodeJS.ProcessEnv} environment - Installation environment.
+ * @param {string} userHome - Current user's home directory.
+ * @param {string|null} invocationDirectory - Directory from which npm was invoked.
+ * @returns {string} Absolute agent configuration root.
+ */
+function resolveAgentConfigurationRoot (
+    agentConfiguration,
+    environment,
+    userHome,
+    invocationDirectory
+) {
+    const configuredRoot = environment[agentConfiguration.configurationEnvironmentVariable];
+
+    if (configuredRoot && configuredRoot.trim()) {
+        return path.resolve(invocationDirectory || userHome, configuredRoot.trim());
+    }
+
+    return path.join(userHome, agentConfiguration.fallbackDirectory);
+}
+
+/**
+ * Adds the Postman installation block without rewriting existing instructions.
+ *
+ * @param {string} instructionFile - Instruction file to update.
+ * @returns {'added'|'existing'} Update result.
+ * @throws {NodeJS.ErrnoException} When the instruction file cannot be read or appended.
+ */
+function addPostmanInstruction (instructionFile) {
+    let existingInstructions = '';
+
+    try {
+        existingInstructions = fileSystem.readFileSync(instructionFile, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+
+    if (existingInstructions.includes(POSTMAN_INSTRUCTION_START) ||
+        existingInstructions.includes(POSTMAN_INSTRUCTION)) {
+        return 'existing';
+    }
+
+    const separator = existingInstructions.length === 0 ?
+        '' :
+        existingInstructions.endsWith('\n') ? '\n' : '\n\n';
+
+    fileSystem.appendFileSync(
+        instructionFile,
+        `${separator}${POSTMAN_INSTRUCTION_BLOCK}\n`,
+        'utf8'
+    );
+
+    return 'added';
+}
+
+/**
+ * @typedef {Object} AgentConfigurationResult
+ * @property {string} name - User-facing agent name.
+ * @property {boolean} detected - Whether its global configuration root exists.
+ * @property {'added'|'existing'|null} instruction - Instruction update outcome.
+ * @property {string|null} errorCode - Sanitized failure classification.
+ */
+
+/**
+ * @typedef {Object} AgentPostConfigurationContext
+ * @property {AgentConfigurationResult} configurationResult - Agent configuration outcome.
+ * @property {string|null} invocationDirectory - Directory from which npm was invoked.
+ */
+
+/**
+ * @param {AgentConfiguration} agentConfiguration - Agent path conventions.
+ * @param {NodeJS.ProcessEnv} environment - Installation environment.
+ * @param {string} userHome - Current user's home directory.
+ * @param {string|null} invocationDirectory - Directory from which npm was invoked.
+ * @returns {AgentConfigurationResult} Detection and update result.
+ */
+function configureAgent (agentConfiguration, environment, userHome, invocationDirectory) {
+    let detected = false;
+
+    try {
+        const configurationRoot = resolveAgentConfigurationRoot(
+            agentConfiguration,
+            environment,
+            userHome,
+            invocationDirectory
+        );
+
+        if (!isDirectory(configurationRoot)) {
+            return {
+                name: agentConfiguration.name,
+                detected,
+                instruction: null,
+                errorCode: null
+            };
+        }
+
+        detected = true;
+
+        return {
+            name: agentConfiguration.name,
+            detected,
+            instruction: addPostmanInstruction(
+                resolveInstructionFile(agentConfiguration, configurationRoot)
+            ),
+            errorCode: null
+        };
+    }
+    catch (error) {
+        return {
+            name: agentConfiguration.name,
+            detected,
+            instruction: null,
+            errorCode: getErrorCode(error)
+        };
+    }
+}
+
+/**
+ * Prints a concise result without exposing user-specific filesystem paths.
+ *
+ * @param {AgentConfigurationResult} result - Agent configuration result.
+ * @returns {void}
+ */
+function printAgentResult (result) {
+    if (result.instruction === 'added') {
+        console.log(`Added Postman CLI availability to ${result.name} global instructions.`);
+    }
+    else if (result.instruction === 'existing') {
+        console.log(`${result.name} global instructions already include Postman CLI.`);
+    }
+    else if (result.errorCode) {
+        printNonBlockingWarning(
+            `Could not update ${result.name} global instructions (${result.errorCode}); ` +
+            'the Postman CLI installation is still usable.'
+        );
+    }
+}
+
+/**
+ * Runs an agent-specific follow-up without affecting other agents or npm.
+ *
+ * @param {AgentConfiguration} agentConfiguration - Agent path conventions.
+ * @param {AgentConfigurationResult} configurationResult - Agent configuration outcome.
+ * @param {string|null} invocationDirectory - Directory from which npm was invoked.
+ * @returns {void}
+ */
+function runAgentPostConfiguration (
+    agentConfiguration,
+    configurationResult,
+    invocationDirectory
+) {
+    if (!agentConfiguration.postConfiguration) {
+        return;
+    }
+
+    try {
+        agentConfiguration.postConfiguration({
+            configurationResult,
+            invocationDirectory
+        });
+    }
+    catch (error) {
+        printNonBlockingWarning(
+            `Could not complete ${agentConfiguration.name} post-configuration ` +
+            `(${getErrorCode(error)}); the Postman CLI installation is still usable.`
+        );
+    }
+}
+
+/**
+ * Configures supported agents after a global npm installation.
+ *
+ * Instruction updates are deliberately non-critical. Installing the Postman CLI
+ * must still succeed when an agent configuration is read-only or malformed.
+ *
+ * @param {NodeJS.ProcessEnv} [environment] - Installation environment.
+ * @returns {void}
+ */
+function runPostInstallation (environment = process.env) {
+    try {
+        if (!isGlobalInstallation(environment)) {
+            return;
+        }
+
+        const userHome = operatingSystem.homedir(),
+            invocationDirectory = resolveInvocationDirectory(environment, userHome),
+            configuredAgents = AGENT_CONFIGURATIONS.map((agentConfiguration) => {
+                return {
+                    agentConfiguration,
+                    configurationResult: configureAgent(
+                        agentConfiguration,
+                        environment,
+                        userHome,
+                        invocationDirectory
+                    )
+                };
+            });
+
+        console.log('Postman CLI is installed and can be used for API Engineering work.');
+        configuredAgents.forEach(({ configurationResult }) => {
+            try {
+                printAgentResult(configurationResult);
+            }
+            catch (error) {
+                printNonBlockingWarning(
+                    `Could not report ${configurationResult.name} configuration ` +
+                    `(${getErrorCode(error)}); the Postman CLI installation is still usable.`
+                );
+            }
+        });
+        configuredAgents.forEach(({ agentConfiguration, configurationResult }) => {
+            runAgentPostConfiguration(
+                agentConfiguration,
+                configurationResult,
+                invocationDirectory
+            );
+        });
+    }
+    catch (error) {
+        printNonBlockingWarning(
+            `Could not configure coding agents after installing Postman CLI (${getErrorCode(error)}); ` +
+            'the Postman CLI installation is still usable.'
+        );
+    }
+}
+
+if (require.main === module) {
+    try {
+        runPostInstallation();
+    }
+    catch (error) {
+        printNonBlockingWarning(
+            `Could not run Postman CLI post-installation (${getErrorCode(error)}); ` +
+            'the Postman CLI installation is still usable.'
+        );
+    }
+    finally {
+        process.exitCode = 0;
+    }
+}
+
+module.exports = {
+    AGENT_CONFIGURATIONS,
+    POSTMAN_INSTRUCTION,
+    addPostmanInstruction,
+    isGlobalInstallation,
+    resolveAgentConfigurationRoot,
+    runPostInstallation
+};