postman-cli 1.63.0 → 1.66.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/man/postman.1

@@ -1,4 +1,4 @@
-.TH POSTMAN 1 "2026-09-23" "v1.63.0" "Postman CLI Manual"
+.TH POSTMAN 1 "2026-09-28" "v1.66.0" "Postman CLI Manual"
 .SH NAME
 postman \- Command\-line companion utility for Postman
 .SH SYNOPSIS
@@ -293,6 +293,12 @@ 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
@@ -376,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).
 
@@ -385,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.
@@ -410,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.
 
@@ -776,7 +860,7 @@ Specify a data file to use for iterations (either JSON or CSV)
 [BETA] Name or id of the view to execute (within \-\-iteration\-data\-dataset). The view's result set drives one iteration per row.
 .TP
 .B \-\-dataset <pathOrDir>
-[BETA] Pass \-\-dataset multiple times to load several .dataset.yaml files (or directories containing them). Each is made available to scripts as pm.datasets(<id>). When provided, auto\-discovery of .dataset.yaml files from the collection's parent repo is disabled. For a cloud collection, scripts address cloud datasets by id via pm.datasets(<id>) (resolved from your `postman login` session). SECURITY: for a cloud collection this does NOT scope access — a script can pm.datasets(<anyId>) for any dataset your session can read. Only run collections you trust against a logged\-in cloud session. (default: )
+[BETA] Pass \-\-dataset multiple times to load several .dataset.yaml files (or directories containing them). Each is made available to collection scripts and local mock handlers as pm.datasets(<id>). When provided, auto\-discovery of .dataset.yaml files from the collection's parent repo is disabled. For a cloud collection, scripts address cloud datasets by id via pm.datasets(<id>) (resolved from your `postman login` session). SECURITY: for a cloud collection this does NOT scope access — a script can pm.datasets(<anyId>) for any dataset your session can read. Only run collections you trust against a logged\-in cloud session. (default: )
 .TP
 .B \-i <id>
 Specify the request/folder id, name, or path to run from the collection. Use a path (e.g. "FolderName/RequestName") to disambiguate items with the same name. Can be specified multiple times to run multiple items (default: )
@@ -872,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
@@ -1350,6 +1443,12 @@ 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.
+.TP
+.B spec delete
+Delete a spec by its cloud ID or local file path. Cannot be undone.
 
 .SS "spec lint"
 Run linting on the given specification by ID or local file path.
@@ -1387,6 +1486,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).
 
@@ -1395,6 +1497,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
 
 
@@ -1607,16 +1711,76 @@ Workspace ID (cloud mode)
 .TP
 .B \-\-api\-key <key>
 Postman API key
+.TP
+.B \-\-force
+Overwrite the collection if one with this name already exists (local mode)
 
 .TP Examples:
 
 Examples:
   postman spec generate collection ./openapi.yaml \-n "My API"
   postman spec generate collection ./openapi.yaml \-n "My API" \-\-folder\-strategy Tags
+  postman spec generate collection ./openapi.yaml \-n "My API" \-\-force
   postman spec generate collection 12345678\-abcd\-1234\-abcd\-1234567890ab \-n "My API"
 
 
 
+.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 "spec delete"
+Delete a spec by its cloud ID or local file path. Cannot be undone.
+
+.B Usage:
+<spec> [options]
+
+.B Options:
+.TP
+.B \-y, \-\-yes
+Delete without asking for confirmation first
+.TP
+.B \-\-api\-key <key>
+Postman API key, used with a cloud ID (defaults to your `postman login` session)
+
+.TP Examples:
+
+Examples:
+  postman spec delete 12345678\-90ab\-cdef\-1234\-567890abcdef
+  postman spec delete ./postman/specs/pet\-store
+  postman spec delete ./postman/specs/pet\-store/index.yaml \-\-yes
+
+
+
 .SS "monitor"
 Run and manage Postman monitors.
 
@@ -2139,12 +2303,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.
 
@@ -2315,6 +2485,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.
 
@@ -2368,6 +2570,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.
 
@@ -2386,7 +2618,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
@@ -2489,10 +2721,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)
@@ -2506,6 +2738,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
@@ -2533,14 +2783,19 @@ Example: less_than(p95, 500) or less_than(error_rate, 5)
 .B \-\-use\-mock <mapping>
 Redirect a variable/host to a local code mock or cloud Mock Server (repeatable). 
 Format: "<{{var}}|host> mock|mock\-server:<path|id> [scenario]" (default: )
+.TP
+.B \-\-dataset <pathOrDir>
+Pass \-\-dataset multiple times to load several .dataset.yaml files (or directories containing them). Each is made available to the handlers of the local mocks started by \-\-use\-mock as pm.datasets(<id>). Local runner only. (default: )
 
 .TP Examples:
 
 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
+  postman performance run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab \-\-use\-mock "{{baseUrl}} mock:./postman/mocks/orders" \-\-dataset ./postman/datasets/Orders
 
 
 .SS "performance list"
@@ -3713,6 +3968,15 @@ 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
+.B \-\-dataset <pathOrDir>
+Pass \-\-dataset multiple times to load several .dataset.yaml files (or directories containing them). Each is made available to the mock's handlers as pm.datasets(<id>). (default: )
 
 .TP Examples:
 
@@ -3721,6 +3985,14 @@ Eg. postman mock run 12345678\-90ab\-cdef\-1234\-567890abcdef  # by id, from Pos
     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
+    postman mock run ./postman/mocks/orders \-\-dataset ./postman/datasets/Orders
+
+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).
 
@@ -4083,6 +4355,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.
 
@@ -6185,6 +6479,9 @@ Materialise the dependencies declared in .postman/resources.yaml (all, or one).
 .TP
 .B dependency update
 Refresh declared dependencies to the latest content from their source (all, or one).
+.TP
+.B dependency remove
+Remove a workspace dependency and delete its local files.
 
 .SS "dependency add"
 Add a Postman collection, environment, or mock as a workspace dependency.
@@ -6289,6 +6586,36 @@ Examples:
 
 
 
+.SS "dependency remove"
+Remove a workspace dependency and delete its local files.
+
+.B Usage:
+[options] <nameOrId>
+
+.B Options:
+.TP
+.B \-\-type <type>
+Only match dependencies of this type (collection, environment, or mock).
+.TP
+.B \-y, \-\-yes
+Skip the confirmation prompt (required outside an interactive terminal).
+.TP
+.B \-\-json
+Output the result as JSON.
+
+.TP Examples:
+
+A <nameOrId> is the cloud id, display name, or on\-disk name of a declared dependency
+(as shown by `postman dependency list`). Removing a collection also removes the
+environments pinned to it, unless another collection pins them too.
+
+Examples:
+  postman dependency remove "My Collection"
+  postman dependency remove 844951\-51ea04bb\-8d1a\-439e\-aa70\-fe91852efcda \-\-yes
+  postman dependency remove Prod \-\-type environment \-\-yes \-\-json
+
+
+
 .SH SEE ALSO
 Full documentation: https://learning.postman.com/docs/postman\-cli/postman\-cli\-overview/
 .SH AUTHOR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postman-cli",
-  "version": "1.63.0",
+  "version": "1.66.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.63.0",
-    "@postman/pm-bin-macos-x64": "1.63.0",
-    "@postman/pm-bin-linux-x64": "1.63.0",
-    "@postman/pm-bin-linux-arm64": "1.63.0",
-    "@postman/pm-bin-windows-x64": "1.63.0"
+    "@postman/pm-bin-macos-arm64": "1.66.0",
+    "@postman/pm-bin-macos-x64": "1.66.0",
+    "@postman/pm-bin-linux-x64": "1.66.0",
+    "@postman/pm-bin-linux-arm64": "1.66.0",
+    "@postman/pm-bin-windows-x64": "1.66.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
+};