postman-cli 1.57.0 → 1.58.0

package/man/postman.1

@@ -1,4 +1,4 @@
-.TH POSTMAN 1 "2026-09-16" "v1.57.0" "Postman CLI Manual"
+.TH POSTMAN 1 "2026-09-17" "v1.58.0" "Postman CLI Manual"
 .SH NAME
 postman \- Command\-line companion utility for Postman
 .SH SYNOPSIS
@@ -127,6 +127,17 @@ Examples:
   $ postman init \-\-visibility personal
 
 
+.SS "whoami"
+Show the Postman account or guest session this CLI session is using.
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-\-json
+Print current identity as machine\-readable JSON.
+
 .SS "skills"
 Check and update the agent skills in this repository.
 
@@ -425,14 +436,14 @@ Exports the cookie jar to a file after completing the run
 .B \-\-verbose
 Show detailed information of collection run and each request sent
 .TP
-.B \-\-mock <path>
-Start a mock server from manifest (.json, .yaml or .yml) file
+.B \-\-mock <pathOrId>
+Start a mock server for the run, its path if it lives in your repository (relative or absolute, e.g. ./postman/mocks/orders) or its id if it lives in Postman cloud (fetched then run locally). An id needs `postman login` (or \-\-postman\-api\-key).
 .TP
 .B \-\-port <port>
-Port for the \-\-mock server; pass "auto" for an OS\-assigned ephemeral port (default: configured port, falls back to an ephemeral one if busy). Only valid with \-\-mock.
+Port for the \-\-mock server (e.g. 4010), or "auto" for a free one. Defaults to the mock's configured port. Only valid with \-\-mock.
 .TP
 .B \-\-use\-mock <mapping>
-Redirect requests for a URL or {{variable}} to a mock during the run. Format: "<url> mock|mock\-server:<path|id> [scenario]". Repeat the flag to redirect multiple URLs (one \-\-use\-mock per mock). Use "mock:<path>" for a local mock manifest (.json/.yaml/.yml), "mock:<id>" for a local mock by id (fetched from the cloud then run locally), or "mock\-server:<id>" to redirect to a deployed mock server's URL. Id\-based references require `postman login` (or \-\-postman\-api\-key). The optional third field selects a scenario (defaults to "default"). (default: )
+Redirect requests for a URL or {{variable}} to a mock during the run. Format: "<url> mock|mock\-server:<path|id> [scenario]". Repeat the flag to redirect several URLs (one \-\-use\-mock each). Use "mock:<path>" for a mock in your repository (path relative or absolute, e.g. ./postman/mocks/orders), "mock:<id>" for a mock in Postman cloud (fetched then run locally), or "mock\-server:<id>" to send requests to a deployed mock server. An id needs `postman login` (or \-\-postman\-api\-key). The optional third field picks a scenario (defaults to "default"). (default: )
 .TP
 .B \-\-simulate <path>
 Start mock servers with fault\-injection scenarios from a .sim.yaml file
@@ -445,6 +456,8 @@ Do not send analytics to Postman
 
 .TP Examples:
 Eg. postman collection run 123456\-45159473\-1e45\-1f34\-5678\-1234567890ab
+    postman collection run <id> \-\-mock ./postman/mocks/orders   # a mock in your repository
+    postman collection run <id> \-\-mock 12345678\-90ab\-cdef\-1234\-567890abcdef  # a mock in Postman cloud
     postman collection run <id> \-\-use\-mock "{{baseurl}} mock:./mock/config.yaml delay"
     postman collection run <id> \-\-use\-mock "{{baseurl}} mock:./a.yaml" \-\-use\-mock "api.com mock\-server:9d8e7f6a"
 
@@ -585,12 +598,15 @@ Verbose output
 .TP
 .B \-\-json
 JSON output
+.TP
+.B \-\-show\-secrets
+Show secret variable values in output
 
 .TP Examples:
 
 Examples:
   postman environment var get baseUrl \-\-environment ./postman/environments/dev.environment.yaml
-  postman environment var get token \-\-environment 123456\-11111111\-2222\-3333\-4444\-555555555555
+  postman environment var get token \-\-environment 123456\-11111111\-2222\-3333\-4444\-5555555 \-\-show\-secrets
 
 
 
@@ -752,7 +768,7 @@ Eg. postman api publish <apiId> \-\-name v1\e
 
 
 .SS "runner"
-Run runners on your own environments for monitoring your APIs
+Where your monitors execute: run and inspect your own self\-hosted runners, and list the Postman\-operated regions available to your team
 
 .B Usage:
 [options] [command]
@@ -761,6 +777,12 @@ Run runners on your own environments for monitoring your APIs
 .TP
 .B runner start
 Start a runner
+.TP
+.B runner list
+List the team's registered self\-hosted runners
+.TP
+.B runner regions
+List the region and private\-runner values valid for monitor create/update \-\-runner, including a static IP where configured
 
 .SS "runner start"
 Start a runner
@@ -803,6 +825,34 @@ Accepted for compatibility; analytics are sent by default
 .B \-\-no\-report\-events
 Do not send analytics to Postman
 
+.SS "runner list"
+List the team's registered self\-hosted runners
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output the runner list as JSON instead of a table
+
+.SS "runner regions"
+List the region and private\-runner values valid for monitor create/update \-\-runner, including a static IP where configured
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output the region list as JSON instead of a table
+
 .SS "spec"
 Lint and validate Specifications from the command line
 
@@ -824,6 +874,12 @@ List local spec files under a path, or (no path) a workspace's cloud specs.
 .TP
 .B spec get
 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).
+.TP
+.B spec create
+Create a new spec in a workspace, or (with path) scaffold a local spec file.
 
 .SS "spec lint"
 Run linting on the given specification by ID or local file path.
@@ -923,8 +979,136 @@ Examples:
 
 
 
+.SS "spec file"
+Add, update, or remove files in a spec (cloud ID or local directory).
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B spec file add
+Add a new file to a spec.
+.TP
+.B spec file update
+Update an existing file in a spec.
+.TP
+.B spec file rm
+Remove a file from a spec.
+
+.SS "spec file add"
+Add a new file to a spec.
+
+.B Usage:
+[options] <spec> <filePath>
+
+.B Options:
+.TP
+.B \-c, \-\-content <content>
+File content (reads from stdin if omitted)
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman spec file add 12345678\-abcd\-1234\-abcd\-1234567890ab schemas/user.yaml \-c "type: object"
+  postman spec file add ./postman/specs/api schemas/user.yaml \-c "type: object"
+  cat schema.yaml | postman spec file add ./postman/specs/api schemas/user.yaml
+
+
+
+.SS "spec file update"
+Update an existing file in a spec.
+
+.B Usage:
+[options] <spec> <filePath>
+
+.B Options:
+.TP
+.B \-c, \-\-content <content>
+New file content (reads from stdin if omitted)
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman spec file update 12345678\-abcd\-1234\-abcd\-1234567890ab index.yaml \-c "openapi: 3.1.0"
+  postman spec file update ./postman/specs/api schemas/user.yaml \-c "type: object"
+  cat schema.yaml | postman spec file update ./postman/specs/api schemas/user.yaml
+
+
+
+.SS "spec file rm"
+Remove a file from a spec.
+
+.B Usage:
+[options] <spec> <filePath>
+
+.B Options:
+.TP
+.B \-y, \-\-yes
+Skip confirmation prompt
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman spec file rm 12345678\-abcd\-1234\-abcd\-1234567890ab schemas/user.yaml \-\-yes
+  postman spec file rm ./postman/specs/api schemas/user.yaml \-\-yes
+
+
+
+.SS "spec create"
+Create a new spec in a workspace, or (with path) scaffold a local spec file.
+
+.B Usage:
+[options] [path]
+
+.B Options:
+.TP
+.B \-n, \-\-name <name>
+Specification name / title
+.TP
+.B \-t, \-\-type <type>
+Spec type: openapi, asyncapi, graphql, protobuf, smithy (default: openapi) (default: openapi)
+.TP
+.B \-\-spec\-version <ver>
+Spec version (e.g. 3.1 for openapi, 3 for protobuf)
+.TP
+.B \-f, \-\-format <fmt>
+File format: yaml or json (openapi/asyncapi only, default: yaml) (default: yaml)
+.TP
+.B \-w, \-\-workspace <id>
+Workspace ID (cloud create, defaults to .postman/resources.yaml)
+.TP
+.B \-\-force
+Overwrite an existing local file
+.TP
+.B \-\-api\-key <key>
+Postman API key
+
+.TP Examples:
+
+Examples:
+  postman spec create \-n "Pet Store"
+  postman spec create \-n "Pet Store" \-w 12345678\-abcd\-1234\-abcd\-1234567890ab
+  postman spec create ./postman/specs/pet\-store/index.yaml \-n "Pet Store"
+  postman spec create ./api.yaml \-n "Events" \-t asyncapi \-f yaml
+  postman spec create ./swagger.yaml \-n "Legacy" \-t openapi \-\-spec\-version 2.0
+  postman spec create ./schema.graphql \-n "My GraphQL API" \-t graphql
+  postman spec create ./service.proto \-n "My Service" \-t protobuf \-\-spec\-version 3
+  postman spec create ./model.smithy \-n "My Model" \-t smithy
+
+
+
 .SS "monitor"
-Invoke a monitor run and display results
+Run and manage Postman monitors.
 
 .B Usage:
 [options] [command]
@@ -933,6 +1117,33 @@ Invoke a monitor run and display results
 .TP
 .B monitor run
 Invoke a monitor run and display results.
+.TP
+.B monitor create
+Create a collection\-based monitor.
+.TP
+.B monitor update
+Update a monitor's schedule, runner, notifications or run options.
+.TP
+.B monitor delete
+Permanently delete a monitor. Prompts for confirmation unless \-\-yes is passed.
+.TP
+.B monitor jobs
+Inspect a monitor's jobs and their per\-region runs.
+.TP
+.B monitor runs
+Inspect a monitor run's attempts.
+.TP
+.B monitor list
+List the monitors visible to you.
+.TP
+.B monitor get
+Show a monitor's configuration.
+.TP
+.B monitor pause
+Pause a monitor, so it stops firing on schedule.
+.TP
+.B monitor resume
+Resume a paused monitor, so it fires on schedule again.
 
 .SS "monitor run"
 Invoke a monitor run and display results.
@@ -942,11 +1153,414 @@ Invoke a monitor run and display results.
 
 .B Options:
 .TP
+.B \-\-api\-key <key>
+Postman API key (defaults to the `postman login` session)
+.TP
 .B \-x, \-\-suppress\-exit\-code
 Specify whether or not to override the default exit code for the current run
 .TP
 .B \-t, \-\-timeout <ms>
 Maximum wait time for run completion in milliseconds (default: 15 minutes) (default: 900000)
+.TP
+.B \-\-async
+Submit the run and return immediately with its job id and Postman URL, without waiting for completion
+.TP
+.B \-\-json
+Output the run's verdict as JSON instead of a table, printing nothing else
+
+.SS "monitor create"
+Create a collection\-based monitor.
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-c, \-\-collection <id>
+Collection to monitor \-\- accepts the id shown in the Postman app, prefixed or bare
+.TP
+.B \-\-name <name>
+Monitor name (defaults to the linked collection's own name)
+.TP
+.B \-\-environment <id>
+Environment to run the monitored collection with
+.TP
+.B \-w, \-\-workspace <id>
+Workspace to create the monitor in (defaults to the workspace named in the local .postman/resources.yaml manifest; required if neither is available)
+.TP
+.B \-\-schedule <cron>
+Cron expression for the monitor's schedule
+.TP
+.B \-\-timezone <tz>
+Time zone for \-\-schedule, e.g. America/New_York (defaults to the host machine's own zone)
+.TP
+.B \-\-runner <value>
+A Postman region name (see `postman runner regions`) or the id of a self\-hosted runner created in Postman (list existing ones with `postman runner list`) to run from (repeatable) (default: )
+.TP
+.B \-\-notify\-email <email>
+Email to notify on a run failure or error (repeatable) (default: )
+.TP
+.B \-\-notification\-limit <n>
+Cap consecutive notifications before they are muted (service range: 1\-99)
+.TP
+.B \-\-retry <n>
+Retries on a failed run (service caps this at 2)
+.TP
+.B \-\-timeout <ms>
+Request timeout in milliseconds
+.TP
+.B \-\-delay <ms>
+Delay between requests in milliseconds
+.TP
+.B \-\-strict\-ssl
+Fail the run when the target's TLS certificate cannot be verified
+.TP
+.B \-\-insecure
+Skip TLS certificate verification for the monitored target
+.TP
+.B \-\-follow\-redirects
+Follow HTTP redirects during the run
+.TP
+.B \-\-block\-redirects
+Do not follow HTTP redirects during the run
+.TP
+.B \-\-dataset\-id <id>
+Dataset to use as iteration data (used together with \-\-dataset\-view\-id)
+.TP
+.B \-\-dataset\-view\-id <id>
+Dataset view to iterate (used together with \-\-dataset\-id)
+.TP
+.B \-\-iteration\-count <n>
+Number of iterations to run
+.TP
+.B \-\-iteration\-strategy <strategy>
+How iteration data is consumed, e.g. round_robin, repeat_last, stop_at_end (requires \-\-iteration\-count, \-\-dataset\-id and \-\-dataset\-view\-id)
+.TP
+.B \-\-no\-run\-now
+Do not trigger an immediate run after creating the monitor
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.TP Examples:
+
+Examples:
+  postman monitor create \-\-collection 12345678\-90ab\-cdef\-1234\-567890abcdef
+  postman monitor create \-\-collection <id> \-\-schedule "0 9 * * MON" \-\-timezone America/New_York
+  postman monitor create \-\-collection <id> \-\-runner us\-east \-\-runner <self\-hosted\-runner\-id>
+  postman monitor create \-\-collection <id> \-\-workspace 12345678\-90ab\-cdef\-1234\-567890abcdef
+
+
+
+.SS "monitor update"
+Update a monitor's schedule, runner, notifications or run options.
+
+.B Usage:
+[options] <monitorId>
+
+.B Options:
+.TP
+.B \-\-name <name>
+New monitor name
+.TP
+.B \-\-schedule <cron>
+New cron expression for the monitor's schedule
+.TP
+.B \-\-timezone <tz>
+Time zone for \-\-schedule, e.g. America/New_York (defaults to the host machine's own zone)
+.TP
+.B \-\-runner <value>
+A Postman region name (see `postman runner regions`) or the id of a self\-hosted runner created in Postman (list existing ones with `postman runner list`) to run from (repeatable; replaces the current set) (default: )
+.TP
+.B \-\-notify\-email <email>
+Email to notify on a run failure or error (repeatable; replaces the current list) (default: )
+.TP
+.B \-\-clear\-notifications
+Remove every notification recipient
+.TP
+.B \-\-notification\-limit <n>
+Cap consecutive notifications before they are muted (service range: 1\-99)
+.TP
+.B \-\-retry <n>
+Retries on a failed run (service caps this at 2)
+.TP
+.B \-\-timeout <ms>
+Request timeout in milliseconds
+.TP
+.B \-\-delay <ms>
+Delay between requests in milliseconds
+.TP
+.B \-\-strict\-ssl
+Fail the run when the target's TLS certificate cannot be verified
+.TP
+.B \-\-insecure
+Skip TLS certificate verification for the monitored target
+.TP
+.B \-\-follow\-redirects
+Follow HTTP redirects during the run
+.TP
+.B \-\-block\-redirects
+Do not follow HTTP redirects during the run
+.TP
+.B \-\-dataset\-id <id>
+Dataset to use as iteration data (used together with \-\-dataset\-view\-id)
+.TP
+.B \-\-dataset\-view\-id <id>
+Dataset view to iterate (used together with \-\-dataset\-id)
+.TP
+.B \-\-iteration\-count <n>
+Number of iterations to run
+.TP
+.B \-\-iteration\-strategy <strategy>
+How iteration data is consumed, e.g. round_robin, repeat_last, stop_at_end (requires \-\-iteration\-count, \-\-dataset\-id and \-\-dataset\-view\-id)
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.TP Examples:
+
+Examples:
+  postman monitor update <id> \-\-schedule "0 */6 * * *" \-\-timezone UTC
+  postman monitor update <id> \-\-notify\-email a@example.com \-\-notify\-email b@example.com
+  postman monitor update <id> \-\-clear\-notifications
+  postman monitor update <id> \-\-runner us\-east \-\-runner <self\-hosted\-runner\-id>
+
+This command cannot change a monitor's linked collection or environment \-\- delete and recreate the monitor instead \-\- and does not pause or resume it; use `monitor pause`/`monitor resume` for that.
+
+
+.SS "monitor delete"
+Permanently delete a monitor. Prompts for confirmation unless \-\-yes is passed.
+
+.B Usage:
+[options] <monitorId>
+
+.B Options:
+.TP
+.B \-y, \-\-yes
+Skip the confirmation prompt
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output the outcome, including any failure, as JSON instead of a plain message
+
+.TP Examples:
+
+Examples:
+  postman monitor delete 12345678\-90ab\-cdef\-1234\-567890abcdef
+  postman monitor delete 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-yes
+  postman monitor delete 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-yes \-\-json
+
+
+
+.SS "monitor jobs"
+Inspect a monitor's jobs and their per\-region runs.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B monitor jobs list
+List a monitor's recent jobs.
+.TP
+.B monitor jobs get
+Report one job's terminal state and its per\-region run outcomes.
+
+.SS "monitor jobs list"
+List a monitor's recent jobs.
+
+.B Usage:
+[options] <monitorId>
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to the `postman login` session)
+.TP
+.B \-\-result <value>
+Filter by outcome, e.g. success, failure, error, abort (server\-validated, not a fixed list)
+.TP
+.B \-\-trigger <value>
+Filter by trigger, e.g. api, schedule, webhook, postman\-cli (server\-validated, not a fixed list)
+.TP
+.B \-\-since <dateTime>
+Only jobs that finished at or after this ISO 8601 date\-time
+.TP
+.B \-\-limit <n>
+Maximum number of jobs to return
+.TP
+.B \-\-cursor <token>
+Opaque pagination cursor
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.SS "monitor jobs get"
+Report one job's terminal state and its per\-region run outcomes.
+
+.B Usage:
+[options] <jobId>
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to the `postman login` session)
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.SS "monitor runs"
+Inspect a monitor run's attempts.
+
+.B Usage:
+[options] [command]
+
+.B Subcommands:
+.TP
+.B monitor runs get
+Report which test assertions ran during one attempt of a run, which failed, and why.
+
+.SS "monitor runs get"
+Report which test assertions ran during one attempt of a run, which failed, and why.
+
+.B Usage:
+[options] <runId>
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to the `postman login` session)
+.TP
+.B \-\-attempt <n>
+Which attempt of the run to show, counting from 0 (default: the latest)
+.TP
+.B \-\-failed\-only
+Show only failed assertions
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.SS "monitor list"
+List the monitors visible to you.
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-w, \-\-workspace <id>
+Filter to monitors in this workspace
+.TP
+.B \-c, \-\-collection <id>
+Filter to monitors on this collection
+.TP
+.B \-\-environment <id>
+Filter to monitors on this environment
+.TP
+.B \-\-runner <id>
+Filter to a Self\-Hosted Runner ID (not a Postman Region). Cannot be combined with \-\-workspace, \-\-collection, \-\-environment, \-\-owner, \-\-team or \-\-active.
+.TP
+.B \-\-owner <id>
+Filter to monitors created by this user id (shown in the Owner column)
+.TP
+.B \-\-team
+Filter to monitors owned by your own team
+.TP
+.B \-\-active <true|false>
+Filter by active state
+.TP
+.B \-\-limit <n>
+Max monitors to return. The service caps page size and rejects a value above it with its own error.
+.TP
+.B \-\-offset <n>
+Not supported: the service accepts this parameter and silently ignores it. Refused locally. Use \-\-cursor instead.
+.TP
+.B \-\-cursor <token>
+Pagination cursor from a previous page's response.
+.TP
+.B \-\-columns <names>
+Comma\-separated columns to show. Defaults to Name, Status, ID, Schedule, Owner, Collection. Also available: State, Notifications, Environment, Runners.
+.TP
+.B \-\-no\-headers
+Omit the header row
+.TP
+.B \-f, \-\-filter <text>
+Show only monitors whose name contains this text (applies to the returned page, case\-insensitive)
+.TP
+.B \-\-sort <field>
+Sort the returned page by "name" or "active"
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.TP Examples:
+
+Eg. postman monitor list
+    postman monitor list \-w 12345678\-90ab\-cdef\-1234\-567890abcdef
+    postman monitor list \-\-active true \-\-sort name
+    postman monitor list \-\-runner 12345678\-90ab\-cdef\-1234\-567890abcdef
+    postman monitor list \-\-columns Name,State \-\-no\-headers
+    postman monitor list \-\-json
+
+
+.SS "monitor get"
+Show a monitor's configuration.
+
+.B Usage:
+[options] <monitorId>
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.TP Examples:
+
+Eg. postman monitor get 12345678\-90ab\-cdef\-1234\-567890abcdef
+    postman monitor get 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-json
+
+
+.SS "monitor pause"
+Pause a monitor, so it stops firing on schedule.
+
+.B Usage:
+[options] <monitorId>
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output as JSON instead of a table
+
+.SS "monitor resume"
+Resume a paused monitor, so it fires on schedule again.
+
+.B Usage:
+[options] <monitorId>
+
+.B Options:
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to POSTMAN_API_KEY, then the `postman login` session)
+.TP
+.B \-\-json
+Output as JSON instead of a table
 
 .SS "workspace"
 Manage workspace resources.
@@ -2279,7 +2893,7 @@ Examples:
 
 
 .SS "mock"
-Run and manage Postman mocks, locally and in the cloud.
+Create, run, and manage Postman mocks — in your repository or in Postman cloud.
 
 .B Usage:
 [options] [command]
@@ -2287,28 +2901,31 @@ Run and manage Postman mocks, locally and in the cloud.
 .B Subcommands:
 .TP
 .B mock generate
-Generate a runnable mock from a Postman collection (v2.0/v2.1/v3 file, or a git\-native v3 collection directory) or an OpenAPI 3.0/3.1 spec file. The source type is auto\-detected. Omit the source to scaffold a sample shopping\-cart mock (POST /cart/items, GET /cart, POST /checkout). Writes a local mock by default, or a cloud mock with \-\-workspace.
+Generate a mock from a Postman collection or an OpenAPI file, or from a built\-in sample shopping\-cart mock (POST /cart/items, GET /cart, POST /checkout). Writes a local mock by default, or a cloud mock with \-\-workspace.
 .TP
 .B mock run
-Start a local mock server from a cloud mock id (fetched and run locally), a manifest file (JSON or YAML), a mock directory (postman/mocks/<slug>), or a .js handler.
+Start a mock using its path if it lives in your repository, or its id if it lives in Postman cloud (fetched and run locally).
+.TP
+.B mock push
+Upload a mock from your repository to Postman cloud (creates it the first time, updates it after).
 .TP
 .B mock deploy
-Deploy a cloud mock into a mock server.
+Turn a mock in Postman cloud into a live mock server others can call over the internet.
 .TP
 .B mock get
-Show a mock's details: a cloud mock by id, or a local mock by path.
+Show a mock's details using its path if it lives in your repository, or its id if it lives in Postman cloud.
 .TP
 .B mock list
-List a workspace's cloud mocks, or (with a path) local mocks under a directory.
+List the mocks in your Postman cloud workspace, or — with a folder path — the mocks in that folder in your repository.
 .TP
 .B mock log
-Browse a deployed mock server's request/response logs by its id (see `mock get`).
+Show the requests a live mock server has received and the responses it sent, using its id.
 .TP
 .B mock delete
-Permanently remove a mock: a cloud mock by id, or a local mock artifact by path.
+Delete a mock using its path if it lives in your repository, or its id if it lives in Postman cloud. Cannot be undone.
 
 .SS "mock generate"
-Generate a runnable mock from a Postman collection (v2.0/v2.1/v3 file, or a git\-native v3 collection directory) or an OpenAPI 3.0/3.1 spec file. The source type is auto\-detected. Omit the source to scaffold a sample shopping\-cart mock (POST /cart/items, GET /cart, POST /checkout). Writes a local mock by default, or a cloud mock with \-\-workspace.
+Generate a mock from a Postman collection or an OpenAPI file, or from a built\-in sample shopping\-cart mock (POST /cart/items, GET /cart, POST /checkout). Writes a local mock by default, or a cloud mock with \-\-workspace.
 
 .B Usage:
 [sourcePath] [options]
@@ -2316,25 +2933,25 @@ Generate a runnable mock from a Postman collection (v2.0/v2.1/v3 file, or a git\
 .B Options:
 .TP
 .B \-o, \-\-output <dir>
-Output directory for the mock (default: postman/mocks/<slug>)
+Folder to save the mock in. Relative or absolute, e.g. ./postman/mocks/orders. Defaults to postman/mocks/<name>.
 .TP
 .B \-n, \-\-name <name>
-Display name for the generated mock. Optional with a source (derived from it); required when generating without a source.
+Name for the mock. Taken from the source when you provide one; required for the sample.
 .TP
 .B \-\-port <port>
-Port the mock server should listen on (default: 4500)
+Port the mock runs on (e.g. 4010) (default: 4500)
 .TP
 .B \-\-force
-Overwrite the config.yaml/default.js in the output directory if it already exists
+Overwrite the mock's files if the target folder already has one
 .TP
 .B \-u, \-\-update <mockPath>
-Update an existing mock in place from the source: path to its config.yaml (or the directory containing it). Regenerates the default scenario handler and preserves the existing name/port. Cannot be combined with \-\-output.
+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.
 .TP
 .B \-w, \-\-workspace <id>
-Create a cloud mock in this Postman workspace instead of a local mock. Cannot be combined with \-\-output/\-\-force/\-\-update.
+Save the mock to this Postman cloud workspace (by id) instead of your repository. Cannot be used with \-\-output, \-\-force, or \-\-update.
 .TP
 .B \-\-api\-key <key>
-Postman API key for \-\-workspace (defaults to the `postman login` session)
+Postman API key to use with \-\-workspace (defaults to your `postman login` session)
 .TP
 .B \-x, \-\-suppress\-exit\-code
 Always exit with code 0, even on failure
@@ -2346,11 +2963,13 @@ Eg. postman mock generate ./my\-collection.json
     postman mock generate \-\-name "My Mock" \-\-port 4010      # sample mock, custom port
     postman mock generate ./openapi.yaml \-\-output ./postman/mocks/api \-\-port 4010
     postman mock generate ./my\-collection.json \-\-update ./postman/mocks/orders
-    postman mock generate ./my\-collection.json \-w 12345678\-90ab\-cdef\-1234\-567890abcdef   # cloud mock
+    postman mock generate ./my\-collection.json \-w 12345678\-90ab\-cdef\-1234\-567890abcdef   # save to Postman cloud
+
+Paths can be relative (e.g. ./my\-collection.json) or absolute (e.g. /Users/me/my\-collection.json).
 
 
 .SS "mock run"
-Start a local mock server from a cloud mock id (fetched and run locally), a manifest file (JSON or YAML), a mock directory (postman/mocks/<slug>), or a .js handler.
+Start a mock using its path if it lives in your repository, or its id if it lives in Postman cloud (fetched and run locally).
 
 .B Usage:
 <mockIdOrPath>
@@ -2358,29 +2977,54 @@ Start a local mock server from a cloud mock id (fetched and run locally), a mani
 .B Options:
 .TP
 .B \-e, \-\-environment <path>
-Path to an environment file (JSON or YAML) for pm.environment
+Path to a file of environment variables for the mock. Relative or absolute, e.g. ./postman/environments/dev.json
 .TP
 .B \-g, \-\-globals <path>
-Path to a globals file (JSON or YAML) for pm.globals
+Path to a file of global variables for the mock. Relative or absolute, e.g. ./globals.json
 .TP
 .B \-p, \-\-port <port>
-Mock server port, or "auto" for an ephemeral one (default: configured port, falls back to an ephemeral one if busy).
+Port to run on (e.g. 4010), or "auto" for a free one. Defaults to the mock's configured port.
 .TP
 .B \-\-api\-key <key>
-Postman API key for cloud mock ids (defaults to the `postman login` session)
+Postman API key, used with a Postman cloud id (defaults to your `postman login` session)
 
 .TP Examples:
-Eg. postman mock run 12345678\-90ab\-cdef\-1234\-567890abcdef  # cloud mock by id
-    postman mock run ./postman/mocks/orders            # a mock directory
-    postman mock run ./postman/mock\-manifest.json
-    postman mock run ./postman/mock\-manifest.yaml
-    postman mock run ./manifest.json \-\-environment ./postman/environments/dev.yaml
-    postman mock run ./manifest.yaml \-\-port auto        # OS\-assigned ephemeral port
-    postman mock run ./manifest.yaml \-\-port 4600        # exact port, errors if busy
+
+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 \-\-port auto    # pick any free port
+    postman mock run ./postman/mocks/orders \-\-port 4600    # use port 4600 (fails if it is in use)
+
+Paths can be relative (e.g. ./postman/mocks/orders) or absolute (e.g. /Users/me/postman/mocks/orders).
+
+
+.SS "mock push"
+Upload a mock from your repository to Postman cloud (creates it the first time, updates it after).
+
+.B Usage:
+<mockPath> [options]
+
+.B Options:
+.TP
+.B \-w, \-\-workspace <id>
+Postman cloud workspace to upload to, by id (defaults to the workspace already linked to this project)
+.TP
+.B \-\-api\-key <key>
+Postman API key (defaults to your `postman login` session)
+
+.TP Examples:
+
+Eg. postman mock push ./postman/mocks/orders        # a mock in your repository
+    postman mock push ./postman/mocks/orders \-w 12345678\-90ab\-cdef\-1234\-567890abcdef
+
+Paths can be relative (e.g. ./postman/mocks/orders) or absolute (e.g. /Users/me/postman/mocks/orders).
+
+After uploading, use `postman mock deploy <id>` to turn it into a live mock server.
 
 
 .SS "mock deploy"
-Deploy a cloud mock into a mock server.
+Turn a mock in Postman cloud into a live mock server others can call over the internet.
 
 .B Usage:
 <mockId> [options]
@@ -2388,38 +3032,40 @@ Deploy a cloud mock into a mock server.
 .B Options:
 .TP
 .B \-w, \-\-workspace <id>
-Workspace that will own the mock server (defaults to the workspace linked in .postman/resources.yaml)
+Postman cloud workspace that will own the server, by id (defaults to the workspace already linked to this project)
 .TP
 .B \-n, \-\-name <name>
-Display name for the mock server (prompts when omitted)
+Name for the mock server (you are asked for one if you skip this)
 .TP
 .B \-s, \-\-slug <slug>
-Slug for the deploy URL (prompts when omitted)
+Short label used in the server's web address, e.g. "my\-mock" (you are asked for one if you skip this)
 .TP
 .B \-\-public
-Deploy as a public mock (default is private; requires an x\-api\-key header)
+Let anyone with the link reach the server. Private by default (callers must send a Postman API key).
 .TP
 .B \-\-auto\-deploy
-Re\-deploy the mock automatically whenever it changes (default off)
+Update the live server automatically whenever the mock changes (off by default)
 .TP
 .B \-y, \-\-yes
-Accept defaults and skip all prompts (private, no auto\-deploy)
+Use the defaults and skip all questions (private, no auto\-deploy)
 .TP
 .B \-\-api\-key <key>
-Postman API key (defaults to the `postman login` session)
+Postman API key (defaults to your `postman login` session)
 
 .TP Examples:
 
-Eg. postman mock deploy 12345678\-90ab\-cdef\-1234\-567890abcdef                 # interactive prompts
+mockId is the id of a mock in Postman cloud (find it with `postman mock list`).
+
+Eg. postman mock deploy 12345678\-90ab\-cdef\-1234\-567890abcdef                 # asks a few questions
     postman mock deploy 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-slug my\-mock \-\-public
     postman mock deploy 12345678\-90ab\-cdef\-1234\-567890abcdef \-n "My Mock" \-s my\-mock \-\-auto\-deploy
-    postman mock deploy 12345678\-90ab\-cdef\-1234\-567890abcdef \-s my\-mock \-y   # non\-interactive
+    postman mock deploy 12345678\-90ab\-cdef\-1234\-567890abcdef \-s my\-mock \-y   # no questions asked
 
-Use `postman workspace push` to push a local mock to Postman cloud.
+Don't have the mock in Postman cloud yet? Upload it first with `postman mock push`.
 
 
 .SS "mock get"
-Show a mock's details: a cloud mock by id, or a local mock by path.
+Show a mock's details using its path if it lives in your repository, or its id if it lives in Postman cloud.
 
 .B Usage:
 <mockIdOrPath> [options]
@@ -2427,20 +3073,22 @@ Show a mock's details: a cloud mock by id, or a local mock by path.
 .B Options:
 .TP
 .B \-\-api\-key <key>
-Postman API key (defaults to the `postman login` session)
+Postman API key (defaults to your `postman login` session)
 .TP
 .B \-\-json
-Output the mock details as JSON instead of a table
+Print the details as machine\-readable data instead of a table
 
 .TP Examples:
 
-Eg. postman mock get 12345678\-90ab\-cdef\-1234\-567890abcdef     # cloud mock by id
-    postman mock get ./postman/mocks/orders                   # local mock by path
+Eg. postman mock get 12345678\-90ab\-cdef\-1234\-567890abcdef     # by id, from Postman cloud
+    postman mock get ./postman/mocks/orders                   # by path, from your repository
     postman mock get ./postman/mocks/orders \-\-json
 
+Paths can be relative (e.g. ./postman/mocks/orders) or absolute (e.g. /Users/me/postman/mocks/orders).
+
 
 .SS "mock list"
-List a workspace's cloud mocks, or (with a path) local mocks under a directory.
+List the mocks in your Postman cloud workspace, or — with a folder path — the mocks in that folder in your repository.
 
 .B Usage:
 [pathOrDir] [options]
@@ -2448,24 +3096,26 @@ List a workspace's cloud mocks, or (with a path) local mocks under a directory.
 .B Options:
 .TP
 .B \-w, \-\-workspace <id>
-Workspace whose cloud mocks to list (defaults to the workspace linked in .postman/resources.yaml)
+Postman cloud workspace whose mocks to list, by id (defaults to the workspace already linked to this project)
 .TP
 .B \-\-api\-key <key>
-Postman API key (defaults to the `postman login` session)
+Postman API key (defaults to your `postman login` session)
 .TP
 .B \-\-json
-Output the mock list as JSON instead of a table
+Print the list as machine\-readable data instead of a table
 
 .TP Examples:
 
-Eg. postman mock list                                                 # linked workspace (cloud)
-    postman mock list \-w 12345678\-90ab\-cdef\-1234\-567890abcdef        # explicit workspace (cloud)
-    postman mock list ./postman/mocks                                # local mocks under a dir
+Eg. postman mock list                                                # your Postman cloud workspace
+    postman mock list \-w 12345678\-90ab\-cdef\-1234\-567890abcdef        # a specific workspace
+    postman mock list ./postman/mocks                                # a folder in your repository
     postman mock list ./postman/mocks \-\-json
 
+The folder path can be relative (e.g. ./postman/mocks) or absolute (e.g. /Users/me/postman/mocks).
+
 
 .SS "mock log"
-Browse a deployed mock server's request/response logs by its id (see `mock get`).
+Show the requests a live mock server has received and the responses it sent, using its id.
 
 .B Usage:
 <mockServerId> [options]
@@ -2473,40 +3123,42 @@ Browse a deployed mock server's request/response logs by its id (see `mock get`)
 .B Options:
 .TP
 .B \-\-limit <n>
-Maximum number of log entries to show (default 50 for \-\-json/non\-interactive output)
+Most entries to show (defaults to 50 when printing machine\-readable output)
 .TP
 .B \-\-method <method>
-Filter by HTTP method (e.g. GET, POST)
+Show only requests of this type (e.g. GET, POST)
 .TP
 .B \-\-status <code|range>
-Filter by response status (e.g. 404 or 5xx)
+Show only these response codes (e.g. 404, or 5xx for any 500\-series)
 .TP
 .B \-\-path <pattern>
-Filter by request path (supports * and ? wildcards)
+Show only requests to matching addresses (use * and ? as wildcards, e.g. /users/*)
 .TP
 .B \-\-since <duration>
-Show logs from this long ago onward (e.g. 2h = the last 2 hours)
+Show entries from this long ago until now (e.g. 2h = the last 2 hours)
 .TP
 .B \-\-until <duration>
-Stop this long ago (e.g. 30m = exclude the most recent 30 minutes)
+Hide entries newer than this (e.g. 30m = skip the most recent 30 minutes)
 .TP
 .B \-\-api\-key <key>
-Postman API key (defaults to the `postman login` session)
+Postman API key (defaults to your `postman login` session)
 .TP
 .B \-\-json
-Output logs as JSON instead of the interactive pager
+Print entries as machine\-readable data instead of the scrollable view
 
 .TP Examples:
 
-Eg. postman mock log 12345678\-90ab\-cdef\-1234\-567890abcdef            # interactive pager
-    postman mock log 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-json     # outputs in JSON
+mockServerId is the id of a live mock server (get it from `postman mock deploy` or `postman mock get`).
+
+Eg. postman mock log 12345678\-90ab\-cdef\-1234\-567890abcdef            # scroll through entries
+    postman mock log 12345678\-90ab\-cdef\-1234\-567890abcdef \-\-json     # machine\-readable output
     postman mock log <mockServerId> \-\-method GET \-\-path '/users/*'
     postman mock log <mockServerId> \-\-status 5xx \-\-limit 50
     postman mock log <mockServerId> \-\-since 7h \-\-until 2h            # between 7h and 2h ago
 
 
 .SS "mock delete"
-Permanently remove a mock: a cloud mock by id, or a local mock artifact by path.
+Delete a mock using its path if it lives in your repository, or its id if it lives in Postman cloud. Cannot be undone.
 
 .B Usage:
 <mockIdOrPath> [options]
@@ -2514,17 +3166,18 @@ Permanently remove a mock: a cloud mock by id, or a local mock artifact by path.
 .B Options:
 .TP
 .B \-y, \-\-yes
-Skip the confirmation prompt
+Delete without asking for confirmation first
 .TP
 .B \-\-api\-key <key>
-Postman API key for cloud mock ids (defaults to the `postman login` session)
+Postman API key, used with a Postman cloud id (defaults to your `postman login` session)
 
 .TP Examples:
 
-Eg. postman mock delete 12345678\-90ab\-cdef\-1234\-567890abcdef   # cloud mock by id
-    postman mock delete ./postman/mocks/orders                 # local mock by path
+Eg. postman mock delete 12345678\-90ab\-cdef\-1234\-567890abcdef   # by id, from Postman cloud
+    postman mock delete ./postman/mocks/orders                 # by path, from your repository
     postman mock delete ./postman/mocks/orders \-\-yes
-    postman mock delete ./postman/mocks/orders/config.yaml \-\-yes
+
+Paths can be relative (e.g. ./postman/mocks/orders) or absolute (e.g. /Users/me/postman/mocks/orders).
 
 
 .SS "application"
@@ -4505,6 +5158,15 @@ Manage workspace dependencies (Postman entities reused from other workspaces).
 .TP
 .B dependency add
 Add a Postman collection, environment, or mock as a workspace dependency.
+.TP
+.B dependency list
+List the workspace dependencies declared in .postman/resources.yaml.
+.TP
+.B dependency install
+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).
 
 .SS "dependency add"
 Add a Postman collection, environment, or mock as a workspace dependency.
@@ -4532,6 +5194,83 @@ Examples:
 
 
 
+.SS "dependency list"
+List the workspace dependencies declared in .postman/resources.yaml.
+
+.B Usage:
+[options]
+
+.B Options:
+.TP
+.B \-\-type <type>
+Only list dependencies of this type (collection, environment, or mock).
+.TP
+.B \-\-json
+Output the result as JSON.
+
+.TP Examples:
+
+Examples:
+  postman dependency list
+  postman dependency list \-\-type collection
+  postman dependency list \-\-json
+
+
+
+.SS "dependency install"
+Materialise the dependencies declared in .postman/resources.yaml (all, or one).
+
+.B Usage:
+[options] [nameOrId]
+
+.B Options:
+.TP
+.B \-\-type <type>
+Only install dependencies of this type (collection, environment, or mock).
+.TP
+.B \-\-json
+Output the result as JSON.
+
+.TP Examples:
+
+Install is the `npm install` of a Postman project: the step to run after a clone or in CI.
+A [nameOrId] is the cloud id, display name, or on\-disk name of a declared
+dependency (as shown by `postman dependency list`).
+
+Examples:
+  postman dependency install
+  postman dependency install \-\-type collection
+  postman dependency install Payments
+
+
+
+.SS "dependency update"
+Refresh declared dependencies to the latest content from their source (all, or one).
+
+.B Usage:
+[options] [nameOrId]
+
+.B Options:
+.TP
+.B \-\-type <type>
+Only update dependencies of this type (collection, environment, or mock).
+.TP
+.B \-\-json
+Output the result as JSON.
+
+.TP Examples:
+
+Update fetches the latest cloud entity for each declared dependency and overwrites its
+files in place. A [nameOrId] is the cloud id, display name, or on\-disk name of a
+declared dependency (as shown by `postman dependency list`).
+
+Examples:
+  postman dependency update
+  postman dependency update \-\-type environment
+  postman dependency update Payments
+
+
+
 .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.57.0",
+  "version": "1.58.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.57.0",
-    "@postman/pm-bin-macos-x64": "1.57.0",
-    "@postman/pm-bin-linux-x64": "1.57.0",
-    "@postman/pm-bin-linux-arm64": "1.57.0",
-    "@postman/pm-bin-windows-x64": "1.57.0"
+    "@postman/pm-bin-macos-arm64": "1.58.0",
+    "@postman/pm-bin-macos-x64": "1.58.0",
+    "@postman/pm-bin-linux-x64": "1.58.0",
+    "@postman/pm-bin-linux-arm64": "1.58.0",
+    "@postman/pm-bin-windows-x64": "1.58.0"
   }
 }