> This page is for Postman Docs, version Latest (v12) (default). > For other versions, use one of these documentation indexes: > - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt > - v11: https://learning.postman.com/v11/llms.txt > For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Postman CLI collection commands `(postman collection)` > Run, create, list, and manage Postman collections and their folders from the command line with collection commands. This topic covers collection-related commands for the [Postman CLI](/docs/postman-cli/postman-cli-overview/). You can run your collections with HTTP requests using the `postman collection run` command. With a paid plan, you can also run collections with gRPC and GraphQL requests. Use the `postman collection migrate` command to migrate collections from the v2.1 JSON format to the v3 YAML format, or the `postman collection import` command to create a collection from a cURL command or a HAR file. You can also use the `postman collection lint` command to check that your collection matches the v3 format schema. Several `postman collection` commands work with collections in the Postman Cloud, including `new`, `get`, `list`, and the `folder` commands. These accept the guest session that [`postman init`](/docs/postman-cli/postman-cli-init/#postman-init) creates, so you can run them without signing in first. You can also sign in with [the `postman login` command](/docs/postman-cli/postman-cli-auth/#postman-login) or pass an `--api-key`. To learn more, see [`postman signup`](/docs/postman-cli/postman-cli-auth/#postman-signup). ## `postman collection run` This command runs a collection and displays run results in the terminal. Specify the collection with its file path if you're running it locally. If you're signed in to Postman, specify the collection with its ID to send the results to the Postman Cloud. Learn how to sign in to Postman with [the `postman login` command](/docs/postman-cli/postman-cli-auth/#postman-login). > **Tip** > > You can find the collection ID in Postman. Click the ![Items icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-items-stroke.svg#icon) **Items** tab, click **Collections** in the sidebar, and select a collection. Then click the ![Info icon](https://assets.postman.com/postman-docs/aether-icons/state-info-stroke.svg#icon) **Info** tab in the right sidebar to view or copy the collection ID. When you run a collection, the Postman CLI runs its requests in order, and one pass through the requests is an iteration. To run the same requests against multiple sets of data, provide iteration data with `--iteration-data`, or with `--iteration-data-dataset` and `--iteration-data-view`. The CLI runs one iteration per row of data, and each row's columns are available to your requests and scripts as variables, such as `{{name}}`. When you're signed in, the CLI uploads run results to Postman, from local runs and CI. This covers collections you run by ID, and Git-native collections you run by path when they're linked to a cloud collection. Results include each test's assertion names, pass or fail status, and error details, and appear on the **Run results** page. The CLI prints a **View on Postman** link to that page, and you can share the URL with your team. A collection run from a local file that isn't linked to Postman runs, but its results aren't uploaded and the CLI prints a message saying so. If the collection's workspace is integrated as a service in the [API Catalog](/docs/api-catalog/cli-reporting/), these runs also surface on that service's **Test** tab, which shows pass rate, assertions, test coverage, and per-endpoint results for the latest run. The full per-run report appears in the **CI Pipeline Runs** table only when the CLI runs in a CI/CD pipeline, which is where the commit and pipeline context comes from. This reporting is supported for HTTP collections. Collections that use other protocols, such as gRPC, WebSocket, MQTT, or Socket.IO, or scripts or authentication that Postman can't include in the report, run but aren't reported. In these cases, the CLI prints a message explaining that the run results won't be uploaded. The command also reports its run results to the API Catalog and Application Inventory by default. To turn this off, pass `--report-events=false`. ### Usage ```bash postman collection run [options] ``` **``** One of the following: * A collection file path if running locally. * A collection ID (UUID format) if signed in to Postman. --- ### Options **`--bail [optional modifiers]`** Specifies whether to stop a collection run on encountering the first error. `--bail` can optionally accept two modifiers: `--folder` and `--failure`. `--folder` skips the entire collection run if there are any errors. If a test fails, `--failure` stops the collection run after completing the current script. --- **`--cookie-jar [path]`** Specifies the file path for a `JSON` cookie jar. This uses the `tough-cookie` library to deserialize the file. --- **`--delay-request [number]`** — default: 0 Specifies a delay (in milliseconds) between requests. --- **`--disable-unicode`** Replaces all symbols in the output with their plain text equivalents. --- **`--environment [UID] or [file-path], -e`** Specifies an environment file path or UID. --- **`--env-var [environment-variable-name]=[environment-variable-value]`** Specifies environment variables in a `key=value` format. Multiple CLI environment variables can be added by using `--env-var` multiple times, for example: `--env-var "this=that" --env-var "alpha=beta"`. --- **`--export-cookie-jar [path]`** Specifies the path where the Postman CLI will output the final cookie jar file after completing a run. This uses the `tough-cookie` library to serialize the file. --- **`--global-var [global-variable-name]=[global-variable-value]`** Specifies global variables in a `key=value` format. Multiple CLI global variables can be added by using `--global-var` multiple times, for example: `--global-var "this=that" --global-var "alpha=beta"`. --- **`--globals [file-path], -g`** Specifies a path to a file containing global variables. Global variables are similar to environment variables but have lower precedence and can be overridden by environment variables having the same name. --- **`--integration-id [ID]`** (This option is only supported in [Postman v11 and earlier](/v11/docs/postman-cli/postman-cli-options).) Specifies an integration ID when using an integration with CI/CD. This sends the Postman CLI results to the correct integration in Postman. --- **`--iteration-count [number], -n`** Specifies the number of times the collection will run when used in conjunction with the iteration data file. --- **`--iteration-data [file-path], -d`** Specifies the local file path to a data file (JSON or CSV) to use for each iteration. You can't use `--iteration-data` together with `--iteration-data-dataset`. --- **`--iteration-data-dataset [dataset-path-or-id]`** Specifies the [dataset](/docs/tests-and-scripts/datasets/overview/) whose view provides the rows used for each iteration. Unlike `--iteration-data`, which reads a static JSON or CSV file, this option draws the iteration rows from a dataset view, so the data can come from a database and be shaped with SQL. Use one of the following: * The path to a local dataset file (`.dataset.yaml`) when running a collection locally. * A cloud dataset ID when running a collection by its ID. This option requires `--iteration-data-view`. You can't use `--iteration-data-dataset` together with `--iteration-data`. --- **`--iteration-data-view [view-name-or-id]`** Specifies the name or unique identifier of the view to run from the [dataset](/docs/tests-and-scripts/datasets/overview/) provided by `--iteration-data-dataset`. The view returns rows that are used for each iteration. This option requires `--iteration-data-dataset`. --- **`--dataset [dataset-path-directory-or-id]`** Makes one or more [datasets](/docs/tests-and-scripts/datasets/overview/) available to collection scripts through `pm.datasets`. You can provide multiple datasets by specifying `--dataset` multiple times. Do one of the following: * When running a collection locally, specify the path to a dataset file (`.dataset.yaml`) or a directory that contains datasets. * When running a collection by its ID, specify a cloud dataset ID. Scripts can then query cloud datasets through `pm.datasets()`, resolved from your `postman login` session. You must pass `--dataset` to make `pm.datasets` available in a collection run by ID. When you use this option, automatic dataset discovery from the collection's parent repository is turned off. > **Warning** > > For a collection run by ID, this option doesn't scope dataset access. A script can call `pm.datasets()` for any dataset your `postman login` session can read, including datasets you didn't pass to `--dataset`. Only run collections you trust against a signed-in session. --- **`-i [requestUID] or [folderUID]`** Runs only the specified folder UID or request UID from the collection. Multiple items can be run in order by specifying `-i` multiple times, for example: `postman collection run collectionUID -i folder1UID -i folder2UID`. --- **`-i [requestName] or [folderName] or [folderPath]`** Runs only the specified folder name or request name from the collection. This option also accepts a folder path relative from the root of the collection. For example, `postman collection run //`. If there are duplicate names, the Postman CLI runs the folder or request that appears first. --- **`--ignore-redirects`** Prevents the Postman CLI from automatically following 3XX redirect responses. --- **`--insecure, -k`** Turns off SSL verification checks and enables self-signed SSL certificates. --- **`--mock `** Starts a [mock](/docs/design-apis/mock-apis/local-mock-servers) for the run, runs the collection against it, then stops it when the run finishes. Accepts the path to a mock in your repository (relative or absolute, for example `./postman/mocks/orders`), or the ID of a mock in the Postman Cloud. When you pass a cloud ID, the CLI fetches the mock and runs it locally. Using an ID requires signing in with [`postman login`](/docs/postman-cli/postman-cli-auth/#postman-login) or passing `--postman-api-key`. --- **`--no-insecure-file-read`** Prevents reading of files situated outside of the working directory. --- **`--output `** Specifies the directory where Postman streams raw run data to YAML files on disk as each request finishes. The following files are created in the specified directory: * `.collection-run-summary.yaml` — A run summary that's created when the run starts and updated throughout the run until it completes, is stopped, or fails. * `.collection-run-executions.yaml` — A multi-document YAML file that streams each completed request to disk as it completes, rather than writing the file all at once at the end of the run. By default, the filename prefix is generated as `-`. This enables multiple runs to write to the same output folder without overwriting one another. If you specify a custom prefix, Postman automatically removes characters that aren't valid in Windows filenames. This option is in beta for Postman Enterprise plans only and can't be used with the `--reporters` option. > **Info** > > To use this option, sign in to Postman with [the `postman login` command](/docs/postman-cli/postman-cli-auth/#postman-login). --- **`--port `** The port for the mock server started by the `--mock` option. Pass `auto` for an OS-assigned ephemeral port. By default, the mock uses its configured port, falling back to an ephemeral port if that port is busy. This option is only valid with `--mock`. --- **`--postman-api-key [api-key]`** Specifies the API key used to load resources from the Postman API. Only supported in the US region. To authenticate in the EU region, use [`postman login --region`](/docs/postman-cli/postman-cli-auth/#postman-login). --- **`--report-events`** Run results are reported to the API Catalog and Application Inventory by default, whether or not you pass `--report-events`. To turn reporting off, pass `--report-events=false`. You can also use `--no-report-events`. --- **`--reporters [reporter], -r [reporter]`** Generates a local report for the collection run in the specified format: `cli`, `json`, `junit`, and `html`. If the `--reporters` option isn't specified, the `cli` report is output by default. Only the `cli` report output is supported for HTTP, gRPC, and GraphQL collections in v3 format (YAML). To learn more, go to [Generate collection run reports using the Postman CLI](/docs/postman-cli/postman-cli-reporters/). --- **`--silent`** Turns off terminal output. --- **`--simulate [file-path]`** Specifies the path to a simulation configuration file in YAML format. This runs the collection with a simulation applied to [mocks](/docs/design-apis/mock-apis/local-mock-servers). To create a simulation and apply it to a mock, see [Create and run simulations in Postman](/docs/design-apis/simulate-conditions). This option is available on [Postman paid plans](https://www.postman.com/pricing/). The option isn't supported for mocks in the Postman Cloud. --- **`--ssl-client-cert-list `** Specifies the path to a client certificates configuration (JSON). --- **`--ssl-client-cert `** Specifies the path to a client certificate (PEM). --- **`--ssl-client-key `** Specifies the path to a client certificate private key. --- **`--ssl-client-passphrase `** Specifies the client certificate passphrase (for a protected key). --- **`--ssl-extra-ca-certs `** Specifies more trusted CA certificates (PEM). --- **`--suppress-exit-code, -x`** Specifies whether to override the default exit code for the current run. --- **`--timeout [number]`** Specifies the time (in milliseconds) to wait for the entire collection run to complete. --- **`--timeout-request [number]`** — default: 0 Specifies a time (in milliseconds) to wait for requests to return a response. --- **`--timeout-script [number]`** — default: 0 Specifies the time (in milliseconds) to wait for scripts to complete. --- **`--verbose`** Shows detailed information for the collection run and each request sent. --- **`--working-dir [path]`** This option is accepted for compatibility, but has no effect. --- **`--use-mock `** Redirects requests to a mock while the collection runs. Each mapping is a URL followed by a mock reference: a local mock (`mock:`) or a deployed mock server (`mock-server:`), with an optional scenario name. Pass `--use-mock` more than once to redirect multiple URLs. When a mapping points to a local mock, the Postman CLI starts it for you. --- ### Examples ```bash postman collection run postman/collections/myCollectionName postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 ``` To drive iterations from a [dataset](/docs/tests-and-scripts/datasets/overview/) view, pass `--iteration-data-dataset` and `--iteration-data-view` together. Use a local dataset file with a local collection, or a cloud dataset ID with a collection run by its ID: ```bash postman collection run postman/collections/myCollectionName \ --iteration-data-dataset ./postman/datasets/customers.dataset.yaml \ --iteration-data-view active-customers postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 \ --iteration-data-dataset 14e30f6c-1234-1234-1234-cafef00dc0de \ --iteration-data-view active-customers ``` Learn more at [Run a collection using the Postman CLI](/docs/postman-cli/postman-cli-run-collection/) and [Use the Postman CLI with GitHub Actions](/docs/postman-cli/postman-cli-github-actions/). ## `postman collection new` Creates a collection. In a local project, this command scaffolds a v3 collection on disk as a directory. A definition file holds the collection's settings, and each request you add is a separate file. To create the collection in a Postman Cloud workspace instead, pass `--workspace`. ### Usage ```bash postman collection new [options] ``` **``** The name for the new collection. --- ### Options **`-w, --workspace `** Creates the collection in a Postman Cloud workspace by ID, instead of scaffolding it locally. Required when the current directory isn't a local project. --- **`--force`** By default, if a collection already exists at the path, the command stops without overwriting it. Use `--force` to rewrite that collection's definition file. Your request files aren't changed. --- **`--json`** Prints the result as JSON for machine-readable output. --- ### Examples ```bash postman collection new "My Collection" postman collection new "My Collection" --workspace 12345678-90ab-cdef-1234-567890abcdef ``` ## `postman collection folder` The `postman collection folder` commands add, read, update, and remove folders in a collection. By default, they edit your local project's collection files. To edit a collection in a Postman Cloud workspace instead, pass the `-w, --workspace` option. ### `postman collection folder add` Creates an empty folder in a collection. After you create a folder, add requests and sub-folders to it. #### Usage ```bash postman collection folder add [folder-name] --collection [options] ``` **`[folder-name]`** The name for the new folder. If you omit it, the folder is named `New folder`. --- #### Options **`--collection `** — required The collection to add the folder to. In cloud mode, this must be the collection's ID. --- **`--folder `** The parent folder to create the new folder in, for example `Users/Admin`. Defaults to the collection root. In cloud mode, this must be a folder ID. --- **`-w, --workspace `** Adds the folder to a collection in a Postman Cloud workspace by ID, instead of editing local files. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection folder add "Auth" --collection "My API" # Create a folder named "New folder" postman collection folder add --collection "My API" # Create a folder nested under a parent folder postman collection folder add "Admin" --collection "My API" --folder Users # Add a folder to a cloud collection (IDs only) postman collection folder add "Auth" --collection --workspace ``` ### `postman collection folder get` Prints a single folder from a collection, with its direct children, without exporting the whole collection. This command is read-only. To read a child folder or request, run `get` on that item. By default, it reads your local project's collection files. To read a folder from a collection in a Postman Cloud workspace instead, pass the `-w, --workspace` option. Locally, this command reads v3 collections only. For a v2.1 JSON collection, run [`postman collection migrate`](#postman-collection-migrate) on it first. #### Usage ```bash postman collection folder get [options] ``` **``** The folder to read, as a display name or `Parent/Name` path. In cloud mode, this must be the folder's ID. --- #### Options **`--collection `** The collection that contains the folder. Required in local mode, given as a name, directory, ID, cloud ID, or path. Optional in cloud mode, where you can look up the folder by its ID alone. --- **`--folder `** Local mode only. The parent folder that scopes a bare-name `` selector, for example `Users`. --- **`-w, --workspace `** Reads the folder from a collection in a Postman Cloud workspace by ID, instead of reading local files. --- **`--json`** Prints only the folder's JSON, without the summary table, for machine-readable output. --- #### Examples ```bash postman collection folder get "Users" --collection "My API" postman collection folder get "Admin" --collection "My API" --folder Users --json # Read a folder from a cloud collection (IDs only) postman collection folder get --workspace ``` ### `postman collection folder update` Updates a folder in a collection. It changes only the fields you pass and leaves the rest untouched. You must pass at least one of `--name`, `--description`, `--auth`, or `--scripts`. #### Usage ```bash postman collection folder update --collection [options] ``` **``** The folder to update, as a display name or `Parent/Name` path. In cloud mode, this must be the folder's ID. --- #### Options **`--collection `** — required The collection that contains the folder. In cloud mode, this must be the collection's ID. --- **`--folder `** The parent folder that scopes a bare-name `` selector, for example `Users`. In cloud mode, this must be a folder ID. --- **`--name `** Renames the folder. --- **`--description `** Sets the folder's description. --- **`--auth `** Sets folder-level authorization. Accepts `none`, `inherit`, `bearer:`, `basic::`, `apikey::[:header|query]`, or `oauth2:`. --- **`--scripts `** Replaces the folder's scripts. Repeatable. The `event` is `prerequest` or `test`, and the value is inline, `@file`, or `-` for standard input. --- **`-w, --workspace `** Updates the folder in a collection in a Postman Cloud workspace by ID, instead of editing local files. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection folder update "Auth" --collection "My API" --name "Authentication" postman collection folder update "Admin" --collection "My API" --folder Users --auth bearer:{{token}} --scripts "test:@check.js" # Update a folder in a cloud collection (IDs only) postman collection folder update --collection --name Auth --workspace ``` ### `postman collection folder rm` Removes a folder from a collection. This is recursive: it deletes the folder and everything inside it, so the command confirms before deleting. #### Usage ```bash postman collection folder rm --collection [options] ``` **``** The folder to remove, as a display name or `Parent/Name` path. In cloud mode, this must be the folder's ID. --- #### Options **`--collection `** — required The collection that contains the folder. In cloud mode, this must be the collection's ID. --- **`--folder `** The parent folder that scopes a bare-name `` selector, for example `Users`. In cloud mode, this must be a folder ID. --- **`-y, --yes`** Skips the confirmation prompt. Required when there's no interactive terminal, including in `--json` mode. Without it in a non-interactive run, the command exits with an error and deletes nothing. --- **`-w, --workspace `** Removes the folder from a collection in a Postman Cloud workspace by ID, instead of editing local files. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection folder rm "Users/Admin" --collection "My API" --yes postman collection folder rm "Admin" --collection "My API" --folder Users --yes # Remove a folder from a cloud collection (IDs only) postman collection folder rm --collection --yes --workspace ``` ## `postman collection get` Fetches a collection by its ID and prints it in the v3 format. Postman converts collections in the older v2.1 format to v3 as needed, so this works for any collection. The stored collection is unchanged. By default, it prints a summary table followed by the collection's full v3 definition. ### Usage ```bash postman collection get [options] ``` **``** The ID of the collection to fetch. --- ### Options **`--api-key `** Your Postman API key. If omitted, the command uses your `postman login` session. --- **`--json`** Prints only the collection's v3 JSON, without the summary table, for machine-readable output. --- ### Examples ```bash postman collection get 12345678-90ab-cdef-1234-567890abcdef ``` ## `postman collection delete` Permanently deletes a collection. Specify a cloud collection by its ID, or a local collection by its directory path. The command prompts for confirmation unless you pass `--yes`. ### Usage ```bash postman collection delete [options] ``` **``** The ID of the cloud collection, or the path to the local collection directory, to delete. --- ### Options **`-y, --yes`** Skips the confirmation prompt. --- **`--api-key `** Your Postman API key, used when deleting a cloud collection. If omitted, the command uses your `postman login` session. --- **`--verbose`** Shows verbose output. --- **`--json`** Prints the result as JSON for machine-readable output. --- ### Examples ```bash postman collection delete postman/collections/Orders postman collection delete postman/collections/Orders --yes postman collection delete 12345678-90ab-cdef-1234-567890abcdef --yes ``` ## `postman collection list` Lists collections. By default, it lists your local project's collections. To list a Postman Cloud workspace's collections instead, pass `--workspace`. ### Usage ```bash postman collection list [options] ``` ### Options **`-w, --workspace `** Lists a Postman Cloud workspace's collections by ID. --- **`-f, --filter `** Filters the results to collections whose name matches the given value. --- **`--json`** Prints the results as JSON for machine-readable output. --- ### Examples ```bash postman collection list postman collection list --workspace 12345678-90ab-cdef-1234-567890abcdef ``` ## `postman collection request` Add, read, update, and remove requests in a v3 collection. These commands edit a local collection by default, or a Postman Cloud collection when you pass `--workspace`. Specify the collection with the `--collection` option, and name the request you're working on as an argument. ### `postman collection request add` Adds an empty request to a collection. Set its details afterward with [`postman collection request update`](#postman-collection-request-update). #### Usage ```bash postman collection request add [request-name] [options] ``` **`[request-name]`** A name for the new request. Defaults to `New request`. --- #### Options **`--collection `** — required The target collection, given as a name, directory, ID, cloud ID, or path. --- **`--folder `** The folder within the collection to add the request to, for example `Users/Admin`. Defaults to the collection's root. --- **`--type `** `'http' | 'graphql' | 'grpc' | 'websocket' | 'socketio'` — default: http The request type. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection request add "Get user" --collection "My API" postman collection request add "List users" --collection "My API" --folder Users ``` ### `postman collection request get` Prints a single request from a collection, with its examples and messages listed as references, without exporting the whole collection. This command works for any request type and is read-only. By default, it reads your local project's collection files. To read a request from a collection in a Postman Cloud workspace instead, pass `--workspace`. Locally, this command reads v3 collections only. For a v2.1 JSON collection, run [`postman collection migrate`](#postman-collection-migrate) on it first. #### Usage ```bash postman collection request get [options] ``` **``** The name or path of the request to read, for example `Users/Get user`. In cloud mode, this must be the request's ID. --- #### Options **`--collection `** The collection that contains the request. Required in local mode, given as a name, directory, ID, cloud ID, or path. Optional in cloud mode, where you can look up the request by its ID alone. --- **`--folder `** Local mode only. A folder to scope a bare-name `` selector, for example `Users/Admin`. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints only the request's JSON, without the summary table, for machine-readable output. --- #### Examples ```bash postman collection request get "Get user" --collection "My API" --folder Users postman collection request get "Users/Get user" --collection "My API" --json # Read a request from a cloud collection (IDs only) postman collection request get --workspace ``` ### `postman collection request update` Updates a request in a collection. Only the fields you pass are changed. #### Usage ```bash postman collection request update [options] ``` **``** The name or path of the request to update. --- #### Options **`--collection `** — required The target collection. For a cloud collection, use its ID. --- **`--folder `** A folder to scope the request selector, for example `Users/Admin`. --- **`--rename `** Renames the request. Works for any request type. --- **`--url `** The request URL. Works for any request type. For an `http` request, its query string replaces the request's existing query parameters. --- **`--method `** The HTTP method. Applies to `http` requests only. --- **`--param `** Replaces the query parameters, and updates the URL's query string to match. Repeat the option for more than one. Applies to `http` requests only. Applied after `--url`. Can't be combined with `--clear-params`. --- **`--clear-params`** Removes every query parameter, including the one in the URL. Applies to `http` requests only. Can't be combined with `--param`. --- **`-d, --body `** The request payload, given inline, as `@file`, or as `-` to read from stdin. For an `http` request, an optional `:` prefix sets the content type: `json`, `text`, `xml`, `html`, `javascript`, `file:`, `urlencoded:key=value`, or `formdata:key=value`. --- **`--variables `** GraphQL variables as JSON. Applies to `graphql` requests only. --- **`--description `** The request description. --- **`--headers `** Replaces the request headers. Repeat the option for more than one. --- **`--auth `** The request authentication. Accepts `none`, `inherit`, `bearer:TOKEN`, `basic:USER:PASS`, `apikey:KEY:VALUE`, or `oauth2:TOKEN`. For an API key, add `:header` or `:query` to control where the key is sent, for example `apikey:KEY:VALUE:header`. --- **`--scripts `** Replaces the request scripts. The `event` is `prerequest` or `test`, and the `script` is given inline, as `@file`, or as `-` to read from stdin. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection request update "Get user" --collection "My API" \ --url "https://api.example.com/users" --method GET postman collection request update "Get user" --collection "My API" --rename "Fetch user" ``` ### `postman collection request rm` Removes a request from a collection. Works for any request type. You can also use the `remove` alias. #### Usage ```bash postman collection request rm [options] ``` **``** The name or path of the request to remove. --- #### Options **`--collection `** — required The target collection. For a cloud collection, use its ID. --- **`--folder `** A folder to scope the request selector. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection request rm "Get user" --collection "My API" ``` ## `postman collection example` The `postman collection example` commands add, read, update, list, and remove examples (saved responses) under a request. By default, they edit your local project's collection files. To edit a collection in a Postman Cloud workspace instead, pass the `-w, --workspace` option. An example always lives under a request, so identify the parent request with the `--request` option. This option is required for `add` and `list`, and optional for `get`, `update`, and `rm` when you address the example by its ID. ### `postman collection example add` Adds an example under a request, with a default `200` status, `OK` status text, and an empty JSON body. Set its details afterward with [`postman collection example update`](#postman-collection-example-update). #### Usage ```bash postman collection example add [example-name] --collection --request [options] ``` **`[example-name]`** A name for the new example. Defaults to `New example`. --- #### Options **`--collection `** — required The collection that contains the request. In cloud mode, this must be the collection's ID. --- **`--request `** — required The parent request to add the example to. In cloud mode, this must be the request's ID. --- **`--folder `** A folder to scope a bare-name `--request` selector, for example `Users/Admin`. In cloud mode, this must be a folder ID. --- **`--type `** — default: http The example type. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection example add "Success" --collection "My API" --request "Get user" postman collection example add --collection "My API" --request Ping ``` ### `postman collection example get` Prints a single example. This command is read-only. #### Usage ```bash postman collection example get --collection [options] ``` **``** The example to read, as a name or ID. In cloud mode, this must be the example's ID. --- #### Options **`--collection `** — required The collection that contains the example. In cloud mode, this must be the collection's ID. --- **`--request `** The parent request. Pass it to disambiguate an example addressed by name. In cloud mode, this must be the request's ID. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints only the example's JSON, without the summary table, for machine-readable output. --- #### Examples ```bash postman collection example get "Success" --collection "My API" --request "Get user" ``` ### `postman collection example list` Lists all examples under a request. #### Usage ```bash postman collection example list --collection --request [options] ``` #### Options **`--collection `** — required The collection that contains the request. In cloud mode, this must be the collection's ID. --- **`--request `** — required The parent request whose examples to list. In cloud mode, this must be the request's ID. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the results as JSON for machine-readable output. --- #### Examples ```bash postman collection example list --collection "My API" --request Ping ``` ### `postman collection example update` Updates an example in a collection. Only the fields you pass are changed. You must pass at least one field. #### Usage ```bash postman collection example update --collection [options] ``` **``** The example to update, as a name or ID. In cloud mode, this must be the example's ID. --- #### Options **`--collection `** — required The collection that contains the example. In cloud mode, this must be the collection's ID. --- **`--request `** The parent request. Optional when you address the example by ID, and required with `--copy-request`. In cloud mode, this must be the request's ID. --- **`--status-code `** The HTTP status code, from `100` to `599`. --- **`--status-text `** The HTTP status text. --- **`-d, --body `** The response body, as `contentType:content`, for example `json:{"ok":true}`. --- **`--headers `** Replaces the response headers. Repeat the option for more than one. --- **`--description `** The example's description. --- **`--rename `** Renames the example. --- **`--url `** The URL of the example's saved request snapshot. --- **`--method `** The method of the example's saved request snapshot. --- **`--request-headers `** Replaces the request snapshot's headers. Repeat the option for more than one. --- **`--request-param `** Replaces the request snapshot's query parameters. Repeat the option for more than one. --- **`--request-body `** The body of the example's saved request snapshot. --- **`--copy-request`** Refreshes the example's request snapshot from the parent request. --- **`--clear-request`** Removes the example's request snapshot. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection example update Success --collection "My API" --request Ping --status-code 404 --status-text "Not Found" postman collection example update Success --collection "My API" --request Ping --body 'json:{"ok":true}' ``` ### `postman collection example rm` Removes an example from its parent request. You can also use the `remove` alias. #### Usage ```bash postman collection example rm --collection [options] ``` **``** The example to remove, as a name or ID. In cloud mode, this must be the example's ID. --- #### Options **`--collection `** — required The collection that contains the example. In cloud mode, this must be the collection's ID. --- **`--request `** The parent request. Pass it to disambiguate an example addressed by name. In cloud mode, this must be the request's ID. --- **`-w, --workspace `** Targets a Postman Cloud workspace by ID. --- **`--json`** Prints the result as JSON for machine-readable output. --- #### Examples ```bash postman collection example rm "Success" --collection "My API" --request "Get user" # Remove an example from a cloud collection (IDs only) postman collection example rm --collection --workspace ``` ## `postman collection migrate` Use the `postman collection migrate` command to migrate your existing v2.1 collection to the new v3 collection format. A new folder containing a YAML file for each request is created and can be run with the `postman collection run` command. ### Usage ```bash postman collection migrate [options] ``` **``** Path to the existing v2.1 collection file to migrate. --- #### Options **`-o, --output `** Specifies the directory to migrate your new collection to. If you don't specify a directory, the Postman CLI saves the new collection in the current directory. --- ### Examples ```bash postman collection migrate your-existing-collection.json postman collection migrate your-existing-collection.json --output path/to/your-new-collection ``` ## `postman collection import` Use the `postman collection import` command to create a v3 collection from a cURL command or a HAR file. By default, it writes the collection to your local project under `postman/collections/`. To create it in a Postman Cloud workspace instead, pass the `-w, --workspace` option. The source can be a file path, `-` to read from standard input, or an inline cURL command. The command auto-detects the format from the file extension or content, or you can set it with the `--type` option. ### Usage ```bash postman collection import [options] ``` **``** The source to import: a file path, `-` to read from standard input, or an inline cURL command. --- ### Options **`--force`** Overwrites an existing local target directory. --- **`--json`** Prints the result as JSON for machine-readable output. --- **`--name `** A display name for the collection. Defaults to a per-format fallback name. --- **`-o, --output `** — default: postman/collections/\ The output directory for the local collection. --- **`--timeout `** — default: 120000 The maximum time to wait for a cloud import, in milliseconds. --- **`--type `** The source format. Accepts `curl` or `har`. Auto-detected from the file extension or content when omitted. --- **`--verbose`** Shows verbose output, including cloud import diagnostics. --- **`-w, --workspace `** Creates the collection in a Postman Cloud workspace by ID, instead of writing it locally. --- ### Examples ```bash postman collection import ./login.curl postman collection import ./session.har --name "Recorded session" postman collection import ./session.har --name "Recorded session" --workspace 12345678-90ab-cdef-1234-567890abcdef ``` ## `postman collection lint` Use the `postman collection lint` command to verify that the collection matches the v3 format schema. It also flags a request whose URL and query parameters don't match, as error `FMT209`. The command warns when a request file in a collection folder doesn't use the required `.request.yaml` suffix. ### Usage ```bash postman collection lint [options] ``` **``** Path to a v3 collection file or directory to lint. --- ### Options **`-f, --fail-severity `** — default: error Exit with a failure code if diagnostics at this severity level or higher are present. Accepted values are `error` and `warning`. With error, the command fails only when errors are present. With warning, the command fails when warnings or errors are present. --- **`-r, --reporter `** — default: cli Specifies the output format. Accepted values are `cli` and `json`. --- ### Examples ```bash postman collection lint ./postman/collections postman collection lint ./postman/collections --fail-severity warning postman collection lint ./postman/collections/collectionName/requestName.request.yaml --reporter json ``` ## `postman collection generate spec` Generates an OpenAPI specification from a collection. Pass a local file path to generate the specification in your local project, or a collection ID to generate it in the Postman Cloud. By default, the command generates an OpenAPI 3.1 specification in YAML. In local mode, the command records the link between the collection and the generated specification in `.postman/workflows.yaml`. You can later apply the collection's changes to the specification with [`postman collection sync spec`](#postman-collection-sync-spec). To generate a collection from a specification instead, see [`postman spec generate collection`](/docs/postman-cli/postman-cli-governance/#postman-spec-generate-collection). ### Usage ```bash postman collection generate spec [options] ``` **``** The collection to generate a specification from, as a local file path or a collection ID. --- ### Options **`--api-key `** Your Postman API key. If omitted, the command uses the `POSTMAN_API_KEY` environment variable or your `postman login` session. --- **`-f, --format `** — default: yaml The output format for the generated specification. Accepts `yaml` or `json`. --- **`-n, --name `** — required A name or title for the generated specification. --- **`--spec-version `** — default: 3.1 The target OpenAPI version for the generated specification. Accepts `3.1`, `3.0`, or `2.0`. --- ### Examples ```bash postman collection generate spec ./postman/collections/my-api --name "My API Spec" postman collection generate spec ./postman/collections/my-api --name "My Spec" --spec-version 3.0 postman collection generate spec ./collection.json --name "My Spec" --format json postman collection generate spec 12345678-90ab-cdef-1234-567890abcdef --name "My Spec" ``` ## `postman collection sync spec` Regenerates a specification from its linked collection, so the specification picks up the collection's latest changes. Run [`postman collection generate spec`](#postman-collection-generate-spec) first to create the link. The command preserves the existing specification's title. Pass a local file path to sync a specification in your local project, or a collection ID to sync a specification in the Postman Cloud. ### Usage ```bash postman collection sync spec [options] ``` **``** The collection whose linked specification to regenerate, as a local file path or a collection ID. --- ### Options **`--api-key `** Your Postman API key. If omitted, the command uses the `POSTMAN_API_KEY` environment variable or your `postman login` session. --- **`--spec-id `** The ID of the specification to sync. Required in cloud mode. --- ### Examples ```bash postman collection sync spec ./postman/collections/my-api postman collection sync spec 12345678-90ab-cdef-1234-567890abcdef --spec-id 87654321-90ab-cdef-1234-567890abcdef ``` ## `postman collection publish` Publishes a cloud collection's public documentation, or sends a request for Community Manager approval when your workspace's governance settings require it. This command works with a cloud collection only, so provide the collection's ID. > **Info** > > This command requires signing in with [the `postman login` command](/docs/postman-cli/postman-cli-auth/#postman-login) or passing `--api-key`. Unlike other `postman collection` commands, the guest session that [`postman init`](/docs/postman-cli/postman-cli-init/#postman-init) creates isn't accepted. ### Usage ```bash postman collection publish [options] ``` **``** The ID of the cloud collection to publish. --- ### Options **`--target `** — default: documentation Where to publish. Only `documentation` is supported. --- **`--environment `** The ID of a cloud environment to bind to the published documentation. --- **`--title `** The SEO title meta tag for the published documentation. Maximum 120 characters. --- **`--description `** The SEO description meta tag for the published documentation. Maximum 320 characters. --- **`--note `** A note for Community Managers reviewing the request. Only applies when your workspace's governance settings route the publish through a request-to-publish approval. --- **`--api-key `** Your Postman API key. If omitted, the command uses your `postman login` session. --- **`--json`** Prints the result as JSON for machine-readable output. --- ### Examples ```bash postman collection publish 12345678-90ab-cdef-1234-567890abcdef postman collection publish 12345678-90ab-cdef-1234-567890abcdef \ --title "My API" --description "Reference docs for My API" ```