postman-cli 1.68.0 → 1.69.0

package/man/postman.1

@@ -1,4 +1,4 @@
-.TH POSTMAN 1 "2026-10-01" "v1.68.0" "Postman CLI Manual"
+.TH POSTMAN 1 "2026-10-01" "v1.69.0" "Postman CLI Manual"
 .SH NAME
 postman \- Command\-line companion utility for Postman
 .SH SYNOPSIS
@@ -300,10 +300,13 @@ Generate artifacts from a collection.
 Sync artifacts generated from a collection.
 .TP
 .B collection request
-Add, update, or remove requests in a local v3 collection.
+Add, get, update, or remove requests in a local v3 collection.
 .TP
 .B collection folder
-Add, update, or remove folders in a local v3 collection.
+Add, get, update, or remove folders in a local v3 collection.
+.TP
+.B collection example
+Add, update, remove, get, or list examples (saved responses) under a request.
 .TP
 .B collection import
 Import a cURL or HAR source into a v3 collection (local, or cloud with \-\-workspace).
@@ -510,7 +513,7 @@ Examples:
 
 
 .SS "collection request"
-Add, update, or remove requests in a local v3 collection.
+Add, get, update, or remove requests in a local v3 collection.
 
 .B Usage:
 [options] [command]
@@ -520,6 +523,9 @@ Add, update, or remove requests in a local v3 collection.
 .B collection request add
 Add an empty request to a local v3 collection (set its details later with `update`).
 .TP
+.B collection request get
+Show a request (any type) in a v3 collection: its own fields, with examples and messages as references.
+.TP
 .B collection request update
 Update a request in a v3 collection (only the fields you pass).
 .TP
@@ -560,6 +566,38 @@ Examples:
 
 
 
+.SS "collection request get"
+Show a request (any type) in a v3 collection: its own fields, with examples and messages as references.
+
+.B Usage:
+[options] <request>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection: name, directory, id, cloud id, or path. Required locally; optional in cloud mode (id only).
+.TP
+.B \-\-folder <id|name|path>
+Folder to scope a bare\-name request selector, e.g. "Users/Admin" (local mode only).
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-json
+JSON output.
+
+.TP Examples:
+
+Prints the request's own fields in the V3 collection format. Its examples (and, for WebSocket / Socket.IO / MQTT, its messages) are listed as references ({ id, $kind } in cloud mode; { name, $kind } plus id when stored, locally). "parent" is added: the containing folder, or the collection for a top\-level request. A linked copy of a reusable request carries "uses" (its source request id) and a source carries "usedBy" (its linked copies); the source may live in another collection, so fetch it by id alone. Select the request by the <request> selector: local — a name or "Folder/Name" path (or \-\-folder to scope a bare name); cloud (\-\-workspace) — a request id, with \-\-collection (an id) optional and no \-\-folder. Read\-only: locally it reads v3 collections only and rejects a v2.1 .json instead of converting it.
+
+Examples:
+  postman collection request get "Get user" \-\-collection "My API"
+  postman collection request get "Users/Get user" \-\-collection "My API" \-\-json
+  postman collection request get <requestId> \-w <workspaceId>
+  postman collection request get <requestId> \-\-collection <collectionId> \-w <workspaceId> \-\-json
+
+
+
 .SS "collection request update"
 Update a request in a v3 collection (only the fields you pass).
 
@@ -665,7 +703,7 @@ Examples:
 
 
 .SS "collection folder"
-Add, update, or remove folders in a local v3 collection.
+Add, get, update, or remove folders in a local v3 collection.
 
 .B Usage:
 [options] [command]
@@ -675,6 +713,9 @@ Add, update, or remove folders in a local v3 collection.
 .B collection folder add
 Add an empty folder to a local v3 collection (set its details later with `update`).
 .TP
+.B collection folder get
+Show a folder in a v3 collection: its own fields and its direct children as references.
+.TP
 .B collection folder update
 Update a folder in a v3 collection (only the fields you pass).
 .TP
@@ -712,6 +753,38 @@ Examples:
 
 
 
+.SS "collection folder get"
+Show a folder in a v3 collection: its own fields and its direct children as references.
+
+.B Usage:
+[options] <folder>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection: name, directory, id, cloud id, or path. Required locally; optional in cloud mode (id only).
+.TP
+.B \-\-folder <id|name|path>
+Parent folder to scope a bare\-name selector, e.g. "Users" (local mode only).
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-json
+JSON output.
+
+.TP Examples:
+
+Prints the folder's own fields in the V3 collection format. Its direct children (requests and sub\-folders) are listed under "items" as references ({ id, $kind } in cloud mode; { name, $kind } plus id when stored, locally) — run `get` on a child to go further. "parent" is added: the containing folder, or the collection for a top\-level folder. 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) optional and no \-\-folder. Read\-only: locally it reads v3 collections only and rejects a v2.1 .json instead of converting it.
+
+Examples:
+  postman collection folder get Users \-\-collection "My API"
+  postman collection folder get "Users/Admin" \-\-collection "My API" \-\-json
+  postman collection folder get <folderId> \-w <workspaceId>
+  postman collection folder get <folderId> \-\-collection <collectionId> \-w <workspaceId> \-\-json
+
+
+
 .SS "collection folder update"
 Update a folder in a v3 collection (only the fields you pass).
 
@@ -790,6 +863,209 @@ Examples:
 
 
 
+.SS "collection example"
+Add, update, remove, get, or list examples (saved responses) under a request.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B collection example add
+Add an empty example under a request (defaults to 200 OK; set details later with `update`).
+.TP
+.B collection example update
+Update an example (only the fields you pass).
+.TP
+.B collection example rm
+Remove an example from a request.
+.TP
+.B collection example get
+Get a single example.
+.TP
+.B collection example list
+List examples under a request.
+
+.SS "collection example add"
+Add an empty example under a request (defaults to 200 OK; set details later with `update`).
+
+.B Usage:
+[options] [example\-name]
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection: name, directory, id, cloud id, or path. Required.
+.TP
+.B \-\-request <id|name|path>
+Parent request (required). Local: name/path/id; cloud: id.
+.TP
+.B \-\-folder <id|name|path>
+Folder to scope the request selector, e.g. "Users/Admin".
+.TP
+.B \-\-type <type>
+Example type: http (default). (default: http)
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-json
+JSON output.
+
+.TP Examples:
+
+Creates a stub example (name + type + default 200/OK/{} response). Configure it with `collection example update`. \-\-request is required.
+
+Examples:
+  postman collection example add "Success" \-\-collection "My API" \-\-request "Get user"
+  postman collection example add \-\-collection "My API" \-\-request Ping
+  postman collection example add "Ok" \-\-collection <cid> \-\-request <rid> \-w <workspaceId>
+
+
+
+.SS "collection example update"
+Update an example (only the fields you pass).
+
+.B Usage:
+[options] <example>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection. Required.
+.TP
+.B \-\-request <id|name|path>
+Parent request (optional; disambiguates local names / \-\-copy\-request).
+.TP
+.B \-\-folder <id|name|path>
+Folder to scope the request selector.
+.TP
+.B \-\-status\-code <code>
+HTTP status code.
+.TP
+.B \-\-status\-text <text>
+HTTP status text.
+.TP
+.B \-d, \-\-body <body>
+Response body as contentType:content.
+.TP
+.B \-\-headers <key:value>
+Replace response headers. Repeatable. (default: )
+.TP
+.B \-\-description <text>
+Example description.
+.TP
+.B \-\-rename <name>
+Rename the example.
+.TP
+.B \-\-url <url>
+Example request snapshot URL.
+.TP
+.B \-\-method <method>
+Example request snapshot method.
+.TP
+.B \-\-request\-headers <key:value>
+Replace request\-snapshot headers. Repeatable. (default: )
+.TP
+.B \-\-request\-param <key:value>
+Replace request\-snapshot query params. Repeatable. (default: )
+.TP
+.B \-\-request\-body <body>
+Example request snapshot body.
+.TP
+.B \-\-copy\-request
+Refresh example.request from the parent request.
+.TP
+.B \-\-clear\-request
+Remove the example.request snapshot.
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-type <type>
+Example type for cloud mode: http. (default: http)
+.TP
+.B \-\-json
+JSON output.
+
+.SS "collection example rm"
+Remove an example from a request.
+
+.B Usage:
+[options] <example>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection. Required.
+.TP
+.B \-\-request <id|name|path>
+Parent request (optional; disambiguates local names).
+.TP
+.B \-\-folder <id|name|path>
+Folder to scope the request selector.
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-type <type>
+Example type for cloud mode: http. (default: http)
+.TP
+.B \-\-json
+JSON output.
+
+.SS "collection example get"
+Get a single example.
+
+.B Usage:
+[options] <example>
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection. Required.
+.TP
+.B \-\-request <id|name|path>
+Parent request (optional; disambiguates local names).
+.TP
+.B \-\-folder <id|name|path>
+Folder to scope the request selector.
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-type <type>
+Example type for cloud mode: http. (default: http)
+.TP
+.B \-\-json
+JSON output.
+
+.SS "collection example list"
+List examples under a request.
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-\-collection <id|name>
+Target collection. Required.
+.TP
+.B \-\-request <id|name|path>
+Parent request (required).
+.TP
+.B \-\-folder <id|name|path>
+Folder to scope the request selector.
+.TP
+.B \-w, \-\-workspace <id>
+Target a Postman cloud workspace by id (cloud mode).
+.TP
+.B \-\-type <type>
+Example type for cloud mode: http. (default: http)
+.TP
+.B \-\-json
+JSON output.
+
 .SS "collection import"
 Import a cURL or HAR source into a v3 collection (local, or cloud with \-\-workspace).
 
@@ -1166,7 +1442,7 @@ Read and update environment variables.
 .B Subcommands:
 .TP
 .B environment var set
-Set one variable in an environment.
+Set one variable in an environment, or link it to a shared\-vault secret.
 .TP
 .B environment var get
 Read one variable value from an environment.
@@ -1175,16 +1451,25 @@ Read one variable value from an environment.
 Remove one variable from an environment.
 
 .SS "environment var set"
-Set one variable in an environment.
+Set one variable in an environment, or link it to a shared\-vault secret.
 
 .B Usage:
-[options] <key> <value>
+[options] <key> [value]
 
 .B Options:
 .TP
 .B \-e, \-\-environment <environment>
 Cloud Environment ID or local environment file path.
 .TP
+.B \-\-secret\-id <id>
+Link this variable to a shared\-vault secret instead of an inline value (from `secret create`'s output).
+.TP
+.B \-\-vault\-id <id>
+Vault id for \-\-secret\-id (auto\-resolved from \-\-workspace when omitted).
+.TP
+.B \-w, \-\-workspace <workspaceId>
+Workspace to resolve \-\-vault\-id from when \-\-secret\-id is given without \-\-vault\-id (falls back to .postman/resources.yaml).
+.TP
 .B \-\-verbose
 Verbose output
 .TP
@@ -1197,6 +1482,8 @@ Examples:
   postman environment var set baseUrl https://api.example.com \e
     \-\-environment ./postman/environments/dev.environment.yaml
   postman environment var set token abc123 \-\-environment 123456\-11111111\-2222\-3333\-4444\-555555555555
+  postman environment var set apiToken \-\-secret\-id b8748ab8\-d1bb\-477f\-95e2\-78625adea75f \e
+    \-\-environment 123456\-11111111\-2222\-3333\-4444\-555555555555 \-\-workspace <workspaceId>
 
 
 
@@ -1496,7 +1783,7 @@ List local spec files under a path, or (no path) a workspace's cloud specs.
 Read a spec definition, including every file of a multi\-file spec.
 .TP
 .B spec file
-Add, update, or remove files in a spec (cloud ID or local directory).
+Get, add, update, or remove files in a spec (cloud ID or local directory).
 .TP
 .B spec create
 Create a new spec in a workspace, or (with path) scaffold a local spec file.
@@ -1586,13 +1873,16 @@ Examples:
 
 
 .SS "spec file"
-Add, update, or remove files in a spec (cloud ID or local directory).
+Get, add, update, or remove files in a spec (cloud ID or local directory).
 
 .B Usage:
 [options] [command]
 
 .B Subcommands:
 .TP
+.B spec file get
+Show a file in a spec: its path, size and content.
+.TP
 .B spec file add
 Add a new file to a spec.
 .TP
@@ -1602,6 +1892,29 @@ Update an existing file in a spec.
 .B spec file rm
 Remove a file from a spec.
 
+.SS "spec file get"
+Show a file in a spec: its path, size and content.
+
+.B Usage:
+[options] <spec> <filePath>
+
+.B Options:
+.TP
+.B \-\-json
+Output as JSON
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman spec file get 12345678\-abcd\-1234\-abcd\-1234567890ab schemas/user.yaml
+  postman spec file get 12345678\-abcd\-1234\-abcd\-1234567890ab index.yaml \-\-json
+  postman spec file get ./postman/specs/api schemas/user.yaml
+
+
+
 .SS "spec file add"
 Add a new file to a spec.
 
@@ -1781,6 +2094,9 @@ Collection ID to sync (required for cloud mode)
 .TP
 .B \-\-api\-key <key>
 Postman API key
+.TP
+.B \-\-force
+Overwrite hand\-written scripts that the spec would otherwise drop
 
 .TP Examples:
 
@@ -6718,6 +7034,50 @@ Examples:
 
 
 
+.SS "secret"
+Create and manage Postman secrets in a team's shared vault.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B secret create
+Create a secret in a team's shared vault.
+
+.SS "secret create"
+Create a secret in a team's shared vault.
+
+.B Usage:
+[options] <key>
+
+.B Options:
+.TP
+.B \-\-team\-id <id>
+Team id (defaults to your authenticated profile's team; must be your own team — the vault rejects any other team id, even one you otherwise have access to)
+.TP
+.B \-w, \-\-workspace <workspaceId>
+Postman workspace ID (falls back to .postman/resources.yaml or .postman/config.json)
+.TP
+.B \-\-api\-key <key>
+Postman API key
+.TP
+.B \-\-value\-stdin
+Read the secret value from stdin instead of prompting
+
+.TP Examples:
+
+The secret value is never accepted as a command\-line argument. Provide it via:
+  \- an interactive masked prompt (default, when stdin is a terminal)
+  \- piped stdin: printf '%s' 's3cr3t' | postman secret create MY_SECRET
+  \- \-\-value\-stdin (explicit, same as piping)
+
+Examples:
+  postman secret create MY_SECRET \-\-team\-id 451 \-\-workspace 00000000\-0000\-0000\-0000\-000000000000
+  printf '%s' 's3cr3t' | postman secret create MY_SECRET \-\-team\-id 451 \-\-value\-stdin
+
+
+
 .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.68.0",
+  "version": "1.69.0",
   "description": "Official Postman CLI - Command-line companion for API development, testing, and automation",
   "keywords": [
     "postman",
@@ -62,10 +62,10 @@
     "scripts/"
   ],
   "optionalDependencies": {
-    "@postman/pm-bin-macos-arm64": "1.68.0",
-    "@postman/pm-bin-macos-x64": "1.68.0",
-    "@postman/pm-bin-linux-x64": "1.68.0",
-    "@postman/pm-bin-linux-arm64": "1.68.0",
-    "@postman/pm-bin-windows-x64": "1.68.0"
+    "@postman/pm-bin-macos-arm64": "1.69.0",
+    "@postman/pm-bin-macos-x64": "1.69.0",
+    "@postman/pm-bin-linux-x64": "1.69.0",
+    "@postman/pm-bin-linux-arm64": "1.69.0",
+    "@postman/pm-bin-windows-x64": "1.69.0"
   }
 }