postman-cli 1.62.0 → 1.63.0

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-23" "v1.63.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
@@ -286,6 +296,9 @@ Fetch a Postman collection in the V3 format and print it.
 .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
@@ -547,6 +560,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.
 
@@ -2164,7 +2303,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:
@@ -3563,7 +3703,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
@@ -3578,7 +3718,7 @@ Postman API key, used with a Postman cloud id (defaults to your `postman login`
 
 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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postman-cli",
-  "version": "1.62.0",
+  "version": "1.63.0",
   "description": "Official Postman CLI - Command-line companion for API development, testing, and automation",
   "keywords": [
     "postman",
@@ -58,10 +58,10 @@
     "man/"
   ],
   "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.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"
   }
 }