postman-cli-completion 1.73.0 → 1.74.0

package/README.md

@@ -119,6 +119,74 @@ After installing for your shell, open a fresh terminal and check each:
 | `postman flows <TAB>` | `list`, `trigger`, `deploy`, `run`, `update`, `list-runs`, `get-run` |
 | `postman --<TAB>` | `--silent`, `--color`, `--version`, `--help` |
 
+## Check your Postman CLI version
+
+The completions are generated for a specific Postman CLI version, so a CLI that has
+drifted from that version may complete commands it does not have (or miss ones it does).
+`doctor` reports both kinds of drift:
+
+```sh
+postman-completion doctor
+```
+
+It performs two independent checks:
+
+1. **Installed CLI vs. the latest published `postman-cli`** — if yours is older, it warns
+   and tells you how to upgrade.
+2. **Installed CLI vs. the version these completions were generated for** — if they differ,
+   it warns and tells you how to update the completions.
+
+```console
+$ postman-completion doctor
+Your Postman CLI is outdated: installed 1.60.0, latest 1.73.0.
+  Upgrade with: npm install -g postman-cli@latest
+These completions were generated for Postman CLI 1.73.0, but 1.60.0 is installed.
+  Completions may offer commands your CLI does not have.
+  Update them with: npm install -g postman-cli-completion@latest
+```
+
+Check 1 queries the npm registry. To skip it — offline, or in a hook where you do not want
+a network call — use `--offline`, which still runs check 2:
+
+```sh
+postman-completion doctor --offline
+```
+
+`doctor` exits **1** when you should act (outdated CLI, or completions that no longer match
+it) and **0** when everything is current, so it works as a shell-startup or CI check. A
+missing Postman CLI is reported as a notice and exits 0. A failed registry lookup never
+fails the command — it degrades to the offline check and explains itself on stderr.
+
+### Automatic notice on install
+
+You do not have to remember to run `doctor`. Installing or updating this package prints a
+notice if your Postman CLI does not match the version the completions were built for:
+
+```console
+$ npm install -g postman-cli-completion
+
+postman-cli-completion:
+  These completions were generated for Postman CLI 1.73.0, but 1.60.0 is installed.
+    Completions may offer commands your CLI does not have.
+    Update them with: npm install -g postman-cli-completion@latest
+
+  Silence this check with POSTMAN_COMPLETION_NO_VERSION_CHECK=1
+```
+
+This check is deliberately conservative:
+
+- **Never fails the install** — it exits 0 on every path, including unexpected errors.
+- **Never touches the network** — the comparison is local, so installs stay fast and
+  offline-safe. The "is my CLI older than the latest release?" question needs the
+  registry, so it belongs to `doctor`.
+- **Silent unless it matters** — nothing is printed when the versions match, when the
+  Postman CLI is not installed, in CI, for non-global installs, or when stderr is not a
+  terminal. Set `POSTMAN_COMPLETION_NO_VERSION_CHECK=1` to disable it entirely.
+
+Because it runs at install time, it catches drift when you install or update this package.
+If you upgrade the Postman CLI itself some time later, run `postman-completion doctor` to
+check on demand.
+
 ## Versioning
 
 The completion scripts are auto-generated from a single source of truth (`spec/commands.json`) and tracked against the upstream Postman CLI by two GitHub Actions workflows:
@@ -130,16 +198,12 @@ So this repo follows the latest published Postman CLI version automatically —
 
 Suspicious catchup diffs (≥30 % flag drop, a known fixed command missing, semver regression) are blocked by `scripts/validate-diff.mjs` and stay open for human review instead of auto-merging.
 
-To check the version the committed spec was generated against:
-
-```sh
-node -p "require('./spec/commands.json').postmanCliVersion"
-```
-
-And your installed Postman CLI:
+To compare the version the completions were built for against your installed CLI, use
+[`postman-completion doctor`](#check-your-postman-cli-version). The underlying values are:
 
 ```sh
-postman --version
+node -p "require('./spec/commands.json').postmanCliVersion"   # what the completions target
+postman --version                                             # what you have installed
 ```
 
 ## License

package/bin/postman-completion.mjs

@@ -2,6 +2,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { checkVersions } from "../lib/version-check.mjs";
 
 // bin/ lives one level under the package root. Resolve completion files relative
 // to this module (NOT process.cwd(), which is the user's shell directory).
@@ -13,6 +14,9 @@ const FILES = {
   fish: resolve(PKG_ROOT, "completions/fish/postman.fish"),
 };
 
+const SPEC_PATH = resolve(PKG_ROOT, "spec/commands.json");
+const PKG_JSON_PATH = resolve(PKG_ROOT, "package.json");
+
 const USAGE = `postman-completion — shell completions for the Postman CLI
 
 Note: this installs the command "postman-completion"; it does NOT shadow the
@@ -22,6 +26,8 @@ Usage:
   postman-completion <zsh|bash|fish>          Print the completion script to stdout
   postman-completion path <zsh|bash|fish>     Print the packaged file's absolute path
   postman-completion path <shell> --dir       Print the file's directory (for zsh fpath)
+  postman-completion doctor                   Check your Postman CLI version for updates
+  postman-completion doctor --offline         Same, without querying the npm registry
   postman-completion --help                   Show this help
 
 Wire it into your shell:
@@ -59,7 +65,30 @@ function printPath(args) {
   process.stdout.write(`${dirOnly ? dirname(file) : file}\n`);
 }
 
-function main(argv) {
+// Exit 0 when everything is current, 1 when the user should act (outdated CLI
+// or completions that no longer match it), so `doctor` is usable in a script.
+async function doctor(args) {
+  const offline = args.includes("--offline");
+  const report = await checkVersions({
+    specPath: SPEC_PATH,
+    packageJsonPath: PKG_JSON_PATH,
+    offline,
+  });
+
+  for (const line of report.lines) process.stdout.write(`${line}\n`);
+
+  // Surface *why* a comparison was skipped, but only when it hid information:
+  // an explicit --offline is the user's own choice and needs no explanation.
+  if (!offline && report.latestError) {
+    process.stderr.write(
+      `postman-completion: could not check npm for the latest version (${report.latestError})\n`,
+    );
+  }
+
+  process.exit(report.level === "warn" ? 1 : 0);
+}
+
+async function main(argv) {
   const [cmd, ...rest] = argv;
 
   if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
@@ -72,6 +101,11 @@ function main(argv) {
     return;
   }
 
+  if (cmd === "doctor") {
+    await doctor(rest);
+    return;
+  }
+
   if (cmd in FILES) {
     emit(cmd);
     return;
@@ -80,4 +114,4 @@ function main(argv) {
   die(`unknown command: ${cmd}\n\n${USAGE}`);
 }
 
-main(process.argv.slice(2));
+main(process.argv.slice(2)).catch((err) => die(err.message));

package/completions/bash/postman.bash

@@ -1,4 +1,4 @@
-# Bash completion for Postman CLI (postman v1.73.0)
+# Bash completion for Postman CLI (postman v1.74.0)
 # Auto-generated by scripts/generate.mjs — DO NOT EDIT
 # Source: spec/commands.json
 # https://github.com/yokawasa/postman-cli-completion
@@ -969,7 +969,7 @@ _postman_flows() {
     if [[ "$cur" == -* ]]; then
       COMPREPLY=( $(compgen -W "-h --help" -- "$cur") )
     else
-      COMPREPLY=( $(compgen -W "list trigger deploy run update list-runs get-run" -- "$cur") )
+      COMPREPLY=( $(compgen -W "list trigger deploy run update delete list-runs get-run" -- "$cur") )
     fi
     return 0
   fi
@@ -979,6 +979,7 @@ _postman_flows() {
     deploy) _postman_flows_deploy ;;
     run) _postman_flows_run ;;
     update) _postman_flows_update ;;
+    delete) _postman_flows_delete ;;
     list-runs) _postman_flows_list_runs ;;
     get-run) _postman_flows_get_run ;;
   esac
@@ -1060,6 +1061,13 @@ _postman_flows_update() {
   esac
 }
 
+_postman_flows_delete() {
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "-y --yes --verbose --debug --json -h --help" -- "$cur") )
+    return 0
+  fi
+}
+
 _postman_flows_list_runs() {
   if [[ "$cur" == -* ]]; then
     COMPREPLY=( $(compgen -W "-w --workspace -f --flow -r --range --verbose --debug --json -h --help" -- "$cur") )
@@ -1193,7 +1201,7 @@ _postman_mock() {
 
 _postman_mock_generate() {
   if [[ "$cur" == -* ]]; then
-    COMPREPLY=( $(compgen -W "-o --output -n --name --port --force -u --update -w --workspace --api-key -x --suppress-exit-code -h --help" -- "$cur") )
+    COMPREPLY=( $(compgen -W "-o --output -n --name --port --stateful --force -u --update -w --workspace --api-key -x --suppress-exit-code -h --help" -- "$cur") )
     return 0
   fi
   case "$prev" in
@@ -1737,10 +1745,13 @@ _postman_spec() {
 
 _postman_spec_lint() {
   if [[ "$cur" == -* ]]; then
-    COMPREPLY=( $(compgen -W "-f --fail-severity --issueType -o --output --workspace-id --report-events --no-report-events -h --help" -- "$cur") )
+    COMPREPLY=( $(compgen -W "-f --fail-severity --issueType -o --output --workspace-id --ruleset --report-events --no-report-events -h --help" -- "$cur") )
     return 0
   fi
   case "$prev" in
+    --ruleset)
+      _postman_filematch '!*.@(json)' "$cur"
+      return 0 ;;
   esac
 }
 
@@ -1905,7 +1916,7 @@ _postman_spec_sync() {
 
 _postman_spec_sync_collection() {
   if [[ "$cur" == -* ]]; then
-    COMPREPLY=( $(compgen -W "--collection-id --api-key --force -h --help" -- "$cur") )
+    COMPREPLY=( $(compgen -W "--collection-id --api-key --force --dry-run -h --help" -- "$cur") )
     return 0
   fi
   case "$prev" in
@@ -2459,7 +2470,7 @@ _postman_logout() {
 
 _postman_signup() {
   if [[ "$cur" == -* ]]; then
-    COMPREPLY=( $(compgen -W "--guest --json -h --help" -- "$cur") )
+    COMPREPLY=( $(compgen -W "--guest --no-push --json -h --help" -- "$cur") )
     return 0
   fi
 }

package/completions/fish/postman.fish

@@ -1,4 +1,4 @@
-# Fish completion for Postman CLI (postman v1.73.0)
+# Fish completion for Postman CLI (postman v1.74.0)
 # Auto-generated by scripts/generate.mjs — DO NOT EDIT
 # Source: spec/commands.json
 # https://github.com/yokawasa/postman-cli-completion
@@ -618,13 +618,14 @@ complete -c postman -n '__fish_seen_subcommand_from environment; and __fish_seen
 complete -c postman -n '__fish_seen_subcommand_from environment; and __fish_seen_subcommand_from lint' -r -k -a '(__fish_complete_suffix .json)'
 
 # ---------- flows ----------
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a list -d 'List all flows'
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a trigger -d 'Trigger a deployed flow'
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a deploy -d 'Deploy a flow (required to trigger it)'
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a run -d 'Run a single flow from a file (e.g. ./path/to/flow.json)'
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a update -d 'Update settings for a deployed flow'
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a list-runs -d 'List run history for a deployed flow'
-complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update list-runs get-run' -a get-run -d 'Analyze a specific flow run'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a list -d 'List all flows'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a trigger -d 'Trigger a deployed flow'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a deploy -d 'Deploy a flow (required to trigger it)'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a run -d 'Run a single flow from a file (e.g. ./path/to/flow.json)'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a update -d 'Update settings for a deployed flow'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a delete -d 'Delete a flow. A flow id deletes the cloud flow; a local flow file path deletes that file only. Prompts for confirmation unless --yes is passed.'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a list-runs -d 'List run history for a deployed flow'
+complete -c postman -n '__postman_using_subcommand flows list trigger deploy run update delete list-runs get-run' -a get-run -d 'Analyze a specific flow run'
 complete -c postman -n '__fish_seen_subcommand_from flows' -s h -l help -d 'display help for command'
 # ---------- flows list ----------
 complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from list' -s w -l workspace -d 'Specify the workspace ID to list flows from' -x
@@ -686,6 +687,12 @@ complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subco
 complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from update' -l debug -d 'Debug output'
 complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from update' -l json -d 'JSON output'
 complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from update' -s h -l help -d 'display help for command'
+# ---------- flows delete ----------
+complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from delete' -s y -l yes -d 'Skip the confirmation prompt'
+complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from delete' -l verbose -d 'Verbose output'
+complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from delete' -l debug -d 'Debug output'
+complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from delete' -l json -d 'JSON output'
+complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from delete' -s h -l help -d 'display help for command'
 # ---------- flows list-runs ----------
 complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from list-runs' -s w -l workspace -d 'Specify the workspace ID' -x
 complete -c postman -n '__fish_seen_subcommand_from flows; and __fish_seen_subcommand_from list-runs' -s f -l flow -d 'Filter sessions by flow ID' -x
@@ -761,6 +768,7 @@ complete -c postman -n '__fish_seen_subcommand_from mock' -s h -l help -d 'displ
 complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -s o -l output -d 'Folder to save the mock in. Relative or absolute, e.g. ./postman/mocks/orders. Defaults to postman/mocks/<name>.' -r
 complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -s n -l name -d 'Name for the mock. Taken from the source when you provide one; required for the sample.' -x
 complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -l port -d 'Port the mock runs on (e.g. 4010) (default: 4500)' -x
+complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -l stateful -d 'Generate pm.state-backed CRUD handlers (create/read/list/update/delete) instead of static example responses. Endpoints that are not CRUD-shaped stay static. Applies to collection or spec sources.'
 complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -l force -d 'Overwrite the mock\'s files if the target folder already has one'
 complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -s u -l update -d 'Update an existing mock from the source instead of creating a new one. Path to the mock, relative or absolute, e.g. ./postman/mocks/orders. Cannot be used with --output.' -r
 complete -c postman -n '__fish_seen_subcommand_from mock; and __fish_seen_subcommand_from generate' -s w -l workspace -d 'Save the mock to this Postman cloud workspace (by id) instead of your repository. Cannot be used with --output, --force, or --update.' -x
@@ -1138,6 +1146,7 @@ complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcom
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -l issueType -d 'Limit linting to a specific issue type. [choices: "syntax"]' -x
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -s o -l output -d 'Output format for the results. [choices: "json", "csv"]' -x
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -l workspace-id -d 'The workspace ID to use for fetching governance rulesets.' -x
+complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -l ruleset -d 'Lint against a local Spectral ruleset.' -r
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -l report-events -d 'Dispatch events to the API Catalog and Application Inventory ingestion pipelines (on by default)'
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -l no-report-events -d 'Do not dispatch events to the API Catalog and Application Inventory ingestion pipelines'
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from lint' -s h -l help -d 'display help for command'
@@ -1208,7 +1217,8 @@ complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcom
 # ---------- spec sync collection ----------
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from sync; and __fish_seen_subcommand_from collection' -l collection-id -d 'Collection ID to sync (required for cloud mode)' -x
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from sync; and __fish_seen_subcommand_from collection' -l api-key -d 'Postman API key' -r
-complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from sync; and __fish_seen_subcommand_from collection' -l force -d 'Overwrite hand-written scripts that the spec would otherwise drop'
+complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from sync; and __fish_seen_subcommand_from collection' -l force -d 'Overwrite hand-written scripts, headers and descriptions that the spec would otherwise drop'
+complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from sync; and __fish_seen_subcommand_from collection' -l dry-run -d 'Report what sync would change and remove without writing anything'
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from sync; and __fish_seen_subcommand_from collection' -s h -l help -d 'display help for command'
 # ---------- spec delete ----------
 complete -c postman -n '__fish_seen_subcommand_from spec; and __fish_seen_subcommand_from delete' -s y -l yes -d 'Delete without asking for confirmation first'
@@ -1476,6 +1486,7 @@ complete -c postman -n '__fish_seen_subcommand_from logout' -s h -l help -d 'dis
 
 # ---------- signup ----------
 complete -c postman -n '__fish_seen_subcommand_from signup' -l guest -d 'Start working as an anonymous guest instead of signing up — no account or browser needed, so it works anywhere. Your work is saved to a temporary workspace you can keep later by running `postman signup`.'
+complete -c postman -n '__fish_seen_subcommand_from signup' -l no-push -d 'Do not push local work to your guest workspace before signing up. By default, work saved under postman/ is pushed first, so the workspace you keep is not empty.'
 complete -c postman -n '__fish_seen_subcommand_from signup' -l json -d 'Print the sign-up details as machine-readable JSON.'
 complete -c postman -n '__fish_seen_subcommand_from signup' -s h -l help -d 'display help for command'
 
@@ -1556,7 +1567,7 @@ complete -c postman -n '__fish_seen_subcommand_from feedback' -l json -d 'Print
 complete -c postman -n '__fish_seen_subcommand_from feedback' -s h -l help -d 'display help for command'
 
 # ---------- performance ----------
-complete -c postman -n '__postman_using_subcommand performance run list get' -a run -d 'Run a performance test on a collection'
+complete -c postman -n '__postman_using_subcommand performance run list get' -a run -d 'Run a performance test on a collection (cloud collection UID or local collection path)'
 complete -c postman -n '__postman_using_subcommand performance run list get' -a list -d 'List past performance runs for a collection, newest first.'
 complete -c postman -n '__postman_using_subcommand performance run list get' -a get -d 'Get one performance run by ID.'
 complete -c postman -n '__fish_seen_subcommand_from performance' -s h -l help -d 'display help for command'

package/completions/zsh/_postman

@@ -1,6 +1,6 @@
 #compdef postman
 compdef _postman postman
-# Zsh completion for Postman CLI (postman v1.73.0)
+# Zsh completion for Postman CLI (postman v1.74.0)
 # Auto-generated by scripts/generate.mjs — DO NOT EDIT
 # Source: spec/commands.json
 # https://github.com/yokawasa/postman-cli-completion
@@ -1173,6 +1173,7 @@ _postman_flows() {
         deploy) _postman_flows_deploy ;;
         run) _postman_flows_run ;;
         update) _postman_flows_update ;;
+        delete) _postman_flows_delete ;;
         list-runs) _postman_flows_list_runs ;;
         get-run) _postman_flows_get_run ;;
       esac
@@ -1188,6 +1189,7 @@ _postman_flows_commands() {
     'deploy:Deploy a flow (required to trigger it)'
     'run:Run a single flow from a file (e.g. ./path/to/flow.json)'
     'update:Update settings for a deployed flow'
+    'delete:Delete a flow. A flow id deletes the cloud flow; a local flow file path deletes that file only. Prompts for confirmation unless --yes is passed.'
     'list-runs:List run history for a deployed flow'
     'get-run:Analyze a specific flow run'
   )
@@ -1272,6 +1274,16 @@ _postman_flows_update() {
     '*:flowId:'
 }
 
+_postman_flows_delete() {
+  _arguments \
+    '(-y --yes)'{-y,--yes}'[Skip the confirmation prompt]' \
+    '--verbose[Verbose output]' \
+    '--debug[Debug output]' \
+    '--json[JSON output]' \
+    '(-h --help)'{-h,--help}'[display help for command]' \
+    '*:flowIdOrPath:'
+}
+
 _postman_flows_list_runs() {
   _arguments \
     '(-w --workspace)'{-w,--workspace}'[Specify the workspace ID]:workspaceId' \
@@ -1442,6 +1454,7 @@ _postman_mock_generate() {
     '(-o --output)'{-o,--output}'[Folder to save the mock in. Relative or absolute, e.g. ./postman/mocks/orders. Defaults to postman/mocks/<name>.]:dir:_files -g "*.json"' \
     '(-n --name)'{-n,--name}'[Name for the mock. Taken from the source when you provide one; required for the sample.]:name' \
     '--port[Port the mock runs on (e.g. 4010) (default\: 4500)]:port' \
+    '--stateful[Generate pm.state-backed CRUD handlers (create/read/list/update/delete) instead of static example responses. Endpoints that are not CRUD-shaped stay static. Applies to collection or spec sources.]' \
     '--force[Overwrite the mock'\''s files if the target folder already has one]' \
     '(-u --update)'{-u,--update}'[Update an existing mock from the source instead of creating a new one. Path to the mock, relative or absolute, e.g. ./postman/mocks/orders. Cannot be used with --output.]:mockPath:_files -g "*.json"' \
     '(-w --workspace)'{-w,--workspace}'[Save the mock to this Postman cloud workspace (by id) instead of your repository. Cannot be used with --output, --force, or --update.]:id' \
@@ -2103,6 +2116,7 @@ _postman_spec_lint() {
     '--issueType[Limit linting to a specific issue type. \[choices\: "syntax"\]]:value' \
     '(-o --output)'{-o,--output}'[Output format for the results. \[choices\: "json", "csv"\]]:value' \
     '--workspace-id[The workspace ID to use for fetching governance rulesets.]:value' \
+    '--ruleset[Lint against a local Spectral ruleset.]:path:_files -g "*.json"' \
     '--report-events[Dispatch events to the API Catalog and Application Inventory ingestion pipelines (on by default)]' \
     '--no-report-events[Do not dispatch events to the API Catalog and Application Inventory ingestion pipelines]' \
     '(-h --help)'{-h,--help}'[display help for command]' \
@@ -2273,7 +2287,8 @@ _postman_spec_sync_collection() {
   _arguments \
     '--collection-id[Collection ID to sync (required for cloud mode)]:id' \
     '--api-key[Postman API key]:key:_files -g "*.(pem|crt|key)"' \
-    '--force[Overwrite hand-written scripts that the spec would otherwise drop]' \
+    '--force[Overwrite hand-written scripts, headers and descriptions that the spec would otherwise drop]' \
+    '--dry-run[Report what sync would change and remove without writing anything]' \
     '(-h --help)'{-h,--help}'[display help for command]' \
     '*:spec:'
 }
@@ -2949,6 +2964,7 @@ _postman_logout() {
 _postman_signup() {
   _arguments \
     '--guest[Start working as an anonymous guest instead of signing up — no account or browser needed, so it works anywhere. Your work is saved to a temporary workspace you can keep later by running `postman signup`.]' \
+    '--no-push[Do not push local work to your guest workspace before signing up. By default, work saved under postman/ is pushed first, so the workspace you keep is not empty.]' \
     '--json[Print the sign-up details as machine-readable JSON.]' \
     '(-h --help)'{-h,--help}'[display help for command]'
 }
@@ -3134,7 +3150,7 @@ _postman_performance() {
 _postman_performance_commands() {
   local -a sub
   sub=(
-    'run:Run a performance test on a collection'
+    'run:Run a performance test on a collection (cloud collection UID or local collection path)'
     'list:List past performance runs for a collection, newest first.'
     'get:Get one performance run by ID.'
   )

package/lib/postinstall.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Postinstall version-drift notice.
+//
+// Runs once, right after `npm i -g postman-cli-completion`, and tells the user
+// if their installed Postman CLI does not match the version these completions
+// were generated for. That moment is the useful one: the user is already doing
+// package management, so an "upgrade this" message is actionable.
+//
+// Hard rules for this file, because postinstall scripts are bad neighbours:
+//
+//   1. NEVER fail the install. Every path exits 0, including unexpected throws.
+//   2. NEVER touch the network. A registry lookup here is exactly the kind of
+//      postinstall behaviour people (rightly) disable; the offline comparison
+//      already catches the common case. `doctor` does the online check on
+//      demand.
+//   3. Say nothing when there is nothing to say, and stay quiet in CI and other
+//      non-interactive installs.
+//
+// The online "is my CLI older than npm latest?" check lives in `doctor`.
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkVersions } from "./version-check.mjs";
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Should we stay silent regardless of what the versions say?
+ *
+ * Suppressed for:
+ *  - an explicit opt-out
+ *  - CI (the notice is for humans; it would just be log noise)
+ *  - a non-TTY stderr, which also covers piped/scripted installs
+ *  - local (non-global) installs: this package is a global CLI helper, so a
+ *    local install is usually a dependency graph artifact, not a user choice
+ */
+export function shouldSuppress(env = process.env, isTTY = process.stderr.isTTY) {
+  if (env.POSTMAN_COMPLETION_NO_VERSION_CHECK === "1") return true;
+  if (env.CI && env.CI !== "false") return true;
+  if (env.npm_config_global !== "true") return true;
+  return !isTTY;
+}
+
+/** Wrap the drift lines in a visually distinct block so it is not lost in npm's output. */
+export function formatNotice(lines) {
+  const body = lines.map((l) => `  ${l}`).join("\n");
+  return `\npostman-cli-completion:\n${body}\n\n  Silence this check with POSTMAN_COMPLETION_NO_VERSION_CHECK=1\n`;
+}
+
+async function main() {
+  if (shouldSuppress()) return;
+
+  const report = await checkVersions({
+    specPath: resolve(PKG_ROOT, "spec/commands.json"),
+    packageJsonPath: resolve(PKG_ROOT, "package.json"),
+    offline: true, // rule 2: no network during install
+    timeoutMs: 3000, // keep the install snappy even if the CLI hangs
+  });
+
+  // Only speak up about real, actionable drift. A matching version, a missing
+  // CLI, or an undeterminable one are all silent: a fresh `npm i -g` of this
+  // package should not lecture someone who has not installed the CLI yet.
+  if (!report.drifted) return;
+
+  process.stderr.write(formatNotice(report.lines));
+}
+
+// Only run when invoked as the postinstall script, not when imported by tests.
+// (Matches the isMainModule guard in scripts/generate.mjs.)
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  // Rule 1: an install must never fail because of this notice.
+  try {
+    await main();
+  } catch {
+    // Intentionally silent — a broken notice is not worth a failed install.
+  }
+  process.exit(0);
+}

package/lib/version-check.mjs

@@ -0,0 +1,261 @@
+// Version drift detection for the Postman CLI.
+//
+// Two independent comparisons, because "outdated" has two meanings here:
+//
+//   1. installed CLI vs. the version these completions were generated against
+//      (spec/commands.json.postmanCliVersion). A mismatch means completions may
+//      offer commands the user's CLI lacks, or miss ones it has. Offline, free.
+//   2. installed CLI vs. the latest published postman-cli on npm. A mismatch
+//      means the user should upgrade. Requires the network.
+//
+// Everything that decides *what* to say is a pure function so it can be tested
+// without a CLI, a network, or a filesystem.
+
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+export const REGISTRY_URL = "https://registry.npmjs.org/postman-cli/latest";
+export const UPGRADE_COMMAND = "npm install -g postman-cli@latest";
+
+/**
+ * Parse a semver-ish string into comparable parts.
+ * Tolerates a leading "v", trailing prerelease/build metadata, and surrounding
+ * whitespace. Returns null for anything we cannot order numerically.
+ */
+export function parseVersion(raw) {
+  if (typeof raw !== "string") return null;
+  const m = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:[-+]([0-9A-Za-z.-]+))?\s*$/.exec(raw);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] ?? null,
+  };
+}
+
+/**
+ * Compare two version strings. Returns -1 / 0 / 1 (a<b / a==b / a>b), or null
+ * if either side is unparseable — callers must treat null as "unknown", never
+ * as "equal", so we don't warn on garbage input.
+ *
+ * A prerelease sorts below the same x.y.z release (1.2.3-beta < 1.2.3), which
+ * matches semver. We deliberately do not order two different prereleases of the
+ * same release against each other beyond a plain string compare.
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return null;
+
+  for (const part of ["major", "minor", "patch"]) {
+    if (pa[part] !== pb[part]) return pa[part] < pb[part] ? -1 : 1;
+  }
+  if (pa.prerelease === pb.prerelease) return 0;
+  if (pa.prerelease === null) return 1; // release > prerelease
+  if (pb.prerelease === null) return -1;
+  return pa.prerelease < pb.prerelease ? -1 : 1;
+}
+
+/**
+ * Read the installed Postman CLI version by shelling out to `postman --version`,
+ * which prints a bare "1.73.0".
+ *
+ * Never throws: a missing CLI, a non-zero exit, or a hang are all normal states
+ * for this tool (the completions package is installed independently of the CLI).
+ * Resolves { version, error } where exactly one side is set.
+ */
+export function detectInstalledVersion({ command = "postman", timeoutMs = 5000 } = {}) {
+  return new Promise((resolvePromise) => {
+    execFile(command, ["--version"], { timeout: timeoutMs }, (err, stdout) => {
+      if (err) {
+        const reason =
+          err.code === "ENOENT"
+            ? `"${command}" not found on PATH`
+            : err.killed
+              ? `"${command} --version" timed out`
+              : `"${command} --version" failed: ${err.message.trim()}`;
+        resolvePromise({ version: null, error: reason });
+        return;
+      }
+      // Some builds print the version among other noise; take the first
+      // semver-looking token so we degrade gracefully rather than fail.
+      const match = /v?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/.exec(stdout ?? "");
+      if (!match) {
+        resolvePromise({
+          version: null,
+          error: `could not parse a version from "${command} --version" output`,
+        });
+        return;
+      }
+      resolvePromise({ version: match[0].replace(/^v/, ""), error: null });
+    });
+  });
+}
+
+/**
+ * Version of the Postman CLI that the committed spec (and therefore the shipped
+ * completion scripts) was generated against.
+ */
+export function readSpecVersion(specPath) {
+  try {
+    const v = JSON.parse(readFileSync(specPath, "utf8")).postmanCliVersion;
+    return typeof v === "string" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The CLI version these completions target.
+ *
+ * Two sources, in order:
+ *   1. spec/commands.json — present in a git checkout, the real source of truth.
+ *   2. this package's own version — release.yml runs `npm version <spec
+ *      version>` before publishing, so an installed copy's version *is* the
+ *      targeted Postman CLI version. This keeps the 348 kB spec out of the
+ *      published tarball.
+ * In a git checkout package.json holds the placeholder
+ * "0.0.0-managed-by-spec". That is technically valid semver (a prerelease of
+ * 0.0.0), so it must be rejected explicitly — otherwise every real CLI would
+ * compare as "newer" and trigger a bogus drift warning.
+ */
+export function resolveTargetVersion({ specPath, packageJsonPath }) {
+  const fromSpec = readSpecVersion(specPath);
+  if (fromSpec) return fromSpec;
+
+  try {
+    const v = JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+    const parsed = parseVersion(v);
+    if (!parsed) return null;
+    // Never trust a 0.0.0 placeholder as a real target version.
+    if (parsed.major === 0 && parsed.minor === 0 && parsed.patch === 0) return null;
+    return v;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask npm for the latest published postman-cli version.
+ * Never throws — offline is an expected state, so failure is reported as data.
+ */
+export async function fetchLatestVersion({
+  url = REGISTRY_URL,
+  timeoutMs = 5000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const signal = AbortSignal.timeout(timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      headers: { Accept: "application/json" },
+      signal,
+    });
+    if (!res.ok) return { version: null, error: `registry request failed: ${res.status}` };
+    const body = await res.json();
+    const version = typeof body?.version === "string" ? body.version : null;
+    return version
+      ? { version, error: null }
+      : { version: null, error: "registry response had no version field" };
+  } catch (err) {
+    const offline = err?.name === "TimeoutError" || err?.name === "AbortError";
+    return {
+      version: null,
+      error: offline ? "registry request timed out" : `registry request failed: ${err.message}`,
+    };
+  }
+}
+
+/**
+ * Decide what to report, given the three versions. Pure.
+ *
+ * `installed` / `spec` / `latest` may each be null (unknown). Returns a report:
+ *   { level, lines, outdated, drifted }
+ * where level is "ok" | "notice" | "warn" and lines are ready to print.
+ */
+export function buildReport({ installed, spec, latest }) {
+  const lines = [];
+  let level = "ok";
+  const bump = (next) => {
+    const rank = { ok: 0, notice: 1, warn: 2 };
+    if (rank[next] > rank[level]) level = next;
+  };
+
+  if (!installed) {
+    return {
+      level: "notice",
+      outdated: false,
+      drifted: false,
+      lines: [
+        "Postman CLI not detected — install it with: npm install -g postman-cli",
+        "(this package only provides shell completions; it does not include the CLI)",
+      ],
+    };
+  }
+
+  // 1. installed vs. latest published — the upgrade suggestion.
+  const vsLatest = compareVersions(installed, latest);
+  const outdated = vsLatest === -1;
+  if (outdated) {
+    bump("warn");
+    lines.push(
+      `Your Postman CLI is outdated: installed ${installed}, latest ${latest}.`,
+      `  Upgrade with: ${UPGRADE_COMMAND}`,
+    );
+  } else if (vsLatest === 1) {
+    lines.push(`Installed Postman CLI ${installed} is newer than npm latest ${latest}.`);
+  } else if (vsLatest === 0) {
+    lines.push(`Postman CLI ${installed} is up to date.`);
+  }
+
+  // 2. installed vs. the spec these completions were built from — the drift
+  //    warning. Reported separately: being on the latest CLI does not guarantee
+  //    the completions were regenerated for it yet, and vice versa.
+  const vsSpec = compareVersions(installed, spec);
+  const drifted = vsSpec !== null && vsSpec !== 0;
+  if (drifted) {
+    bump("warn");
+    lines.push(
+      `These completions were generated for Postman CLI ${spec}, but ${installed} is installed.`,
+      vsSpec === -1
+        ? "  Completions may offer commands your CLI does not have."
+        : "  Completions may be missing commands your CLI supports.",
+      "  Update them with: npm install -g postman-cli-completion@latest",
+    );
+  } else if (vsSpec === 0) {
+    lines.push(`Completions match your installed CLI (${installed}).`);
+  }
+
+  return { level, lines, outdated, drifted };
+}
+
+/**
+ * Run both comparisons and build the report.
+ * `offline: true` skips the registry lookup entirely (no network, no delay).
+ */
+export async function checkVersions({
+  specPath,
+  packageJsonPath,
+  offline = false,
+  command = "postman",
+  timeoutMs = 5000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const spec = resolveTargetVersion({ specPath, packageJsonPath });
+  const [{ version: installed, error: installError }, latestResult] = await Promise.all([
+    detectInstalledVersion({ command, timeoutMs }),
+    offline
+      ? Promise.resolve({ version: null, error: "skipped (offline)" })
+      : fetchLatestVersion({ timeoutMs, fetchImpl }),
+  ]);
+
+  const report = buildReport({ installed, spec, latest: latestResult.version });
+  return {
+    ...report,
+    installed,
+    spec,
+    latest: latestResult.version,
+    installError,
+    latestError: latestResult.error,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postman-cli-completion",
-  "version": "1.73.0",
+  "version": "1.74.0",
   "description": "Shell completions for the Postman CLI (zsh, bash, fish)",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "completions/zsh/_postman",
     "completions/bash/postman.bash",
     "completions/fish/postman.fish",
@@ -19,6 +20,7 @@
     "generate": "node scripts/generate.mjs",
     "generate:check": "node scripts/generate.mjs --check",
     "check-version": "node scripts/check-version.mjs",
+    "postinstall": "node lib/postinstall.mjs",
     "test": "node --test tests/*.test.mjs",
     "prepublishOnly": "node scripts/generate.mjs --check && node --test tests/*.test.mjs"
   },