Postman CLI command options

This topic covers the commands and options supported by the Postman CLI.

Basic command line options

postman

The base command of the Postman CLI is postman. Run this command with the syntax and options detailed below.

Options

Option	Details
--help, -h	Returns information about Postman CLI commands and options.
--version, -v	Returns the version number for the Postman CLI.

Example

postman -v

Sign in and out

You can use the Postman CLI to sign in and out of Postman with the login and logout commands.

postman login

This command authenticates the user and locally caches the Postman API key. The login command requires one option, --with-api-key, that accepts the Postman API key. Signing in is required once per session. You remain signed in until you use the logout command or your Postman API key expires.

Options

Option	Details
--with-api-key <api-key>	Authenticate the user with the given API key.

Example

postman login --with-api-key ABCD-1234-1234-1234-1234-1234

postman logout

This command signs you out of Postman and deletes the stored API key.

Example

postman logout

Run collections

You can run your collections with the postman collection run command:

postman collection run

This command runs a collection and sends the run results to the Postman cloud. You can specify the collection with its file path or Collection ID.

You can find the collection ID in Postman. Select Collections in the sidebar and select a collection. Then select Info in the right sidebar to view or copy the collection ID.

Options

Option	Details
--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.
--color [value]	Controls colors in the CLI output. Accepts on, off, and auto. The default is auto. With auto, the Postman CLI attempts to automatically turn color on or off based on the color support in the terminal. This behavior can be changed by using the on or off value.
--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]	Specifies a delay (in milliseconds) between requests. The default is 0.
--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]	Specifies an integration ID when using an integration with CI/CD. This sends the Postman CLI results to the correct integration in Postman. When you generate the Postman CLI command for a Git integrated API collection, the integration ID is automatically added to the command. To learn how to generate the Postman CLI command with the integration ID, go to Configure the Postman CLI for CI.
--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] or [URL], -d	Specifies a data source file (JSON or CSV) to be used for iteration. You can specify a local file path or a URL to the data file.
-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]	Runs only the specified folder name or request name from the collection. 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.
--no-insecure-file-read	Prevents reading of files situated outside of the working directory.
--silent	Turns off terminal output.
--ssl-client-cert-list <path>	Specifies the path to a client certificates configuration (JSON).
--ssl-client-cert <path>	Specifies the path to a client certificate (PEM).
--ssl-client-key <path>	Specifies the path to a client certificate private key.
--ssl-client-passphrase <passphrase>	Specifies the client certificate passphrase (for a protected key).
--ssl-extra-ca-certs <path>	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]	Specifies a time (in milliseconds) to wait for requests to return a response. The default is 0.
--timeout-script [number]	Specifies the time (in milliseconds) to wait for scripts to complete. The default is 0.
--verbose	Shows detailed information for the collection run and each request sent.
--working-dir [path]	Sets the path of the working directory to use while reading files with relative paths. This defaults to the current directory.
--reporters [reporter], -r [reporter]	Generates a local report for the collection run in the specified format: cli, json, and junit. If the --reporters option isn't specified, the cli report is output by default. To learn more, go to Generate collection run reports using the Postman CLI.

Examples

postman collection run /myCollectionFolderName/myCollectionFile.json

postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Governance and security

API governance is the practice of applying a defined set of standards consistently across the API design and testing phases of your development process. The Postman CLI includes a command that checks your API definitions against your team's configured Postman API Governance and API Security rules. (This feature is available for Enterprise teams only).

postman api lint

This command runs validation checks for governance and security rules against the API definition provided in the Postman config file, a local file, or a UUID. The api lint command shows a warning if it's unable to find the API ID to send data back to Postman.

This command supports APIs that are stored on Postman and aren't linked to Git.

Options

Option	Details
--fail-severity [severity], -f	Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARN, and ERROR (default).
--suppress-exit-code, -x	Specifies whether to override the default exit code for the current run.

Example

postman api lint my-definition-file.json
postman api lint 8854915-bb7236b2-536e-4bdc-bfa2-fbe2fe1941eb

Publish an API version

You can publish API versions from the command line with the Postman CLI. Use the Postman CLI to automate the API version publishing process.

postman publish api

Publish a snapshot of an API for the given apiId. All elements linked to the API are published by default. You can choose which elements to publish by using other command options.

When publishing an API that's linked with Git, you must enter the command from inside the local Git repo. Also, you must provide paths to the schema directory and collection paths instead of IDs.

Options

Option	Details
--name <name>	Specifies the name of the version to publish.
--release-notes <releaseNotes>	Enter release notes as a string in quotes for the version to publish. This option supports Markdown.
--collections <collectionIds/paths...>	Specifies the collections to publish. If the API is linked with Git, provide the filePath instead of the ID.
--api-definition <apiDefinitionId/directory/file>	Specifies the API definition to publish. If the API is linked with Git, provide the schemaDirectoryPath or schemaRootFilePath instead of the ID.
--do-not-poll	Specifies not to poll for completion status of the publish action.
--suppress-exit-code, -x	Specifies whether to override the default exit code for the current run.

Example for repos not linked with Git

postman api publish <apiId> --name v1\
--release-notes "# Some release notes information"\
--collections <collectionId1> <collectionId2>\
--api-definition <apiDefinitionId>

Examples for repos linked with Git

The options for the api publish command differ depending on if you specified a schema folder or schema root file when setting up the Git integration. Git integrations added in Postman v10.18 or later use a schema root file. Git integrations added in other Postman versions use a schema folder. Learn more about connecting an API to a Git repository.

• If the API uses a schema folder, publish the API using the --api-definition <schemaDirectoryPath> option:

  postman api publish <apiId> --name v1\
  --release-notes "# Some release notes information"\
  --collections <collectionPath1> <collectionPath2>\
  --api-definition <schemaDirectoryPath>
  

• If the API uses a schema root file, publish the API using the --api-definition <schemaRootFilePath> option:

  postman api publish <apiId> --name v1\
  --release-notes "# Some release notes information"\
  --collections <collectionPath1> <collectionPath2>\
  --api-definition <schemaRootFilePath>
  

If you specify a file when a folder is required, or a folder when a file is required, the api publish command returns the following error: API Definition <file/folder> isn't part of API <apiId>. Try the command again using the other option.