Postman CLI command options

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

Basic command line options


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


--help, -hReturns information about Postman CLI commands and options.
--version, -vReturns the version number for the Postman CLI.


postman -v

Signing 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. login requires one option, --with-api-key, that accepts the Postman API key. The login command is required once per session. You remain signed in until you use the logout command or your Postman API key expires.


--with-api-key [api-key]Authenticate the user with the given API key.


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.


postman logout

Running collections

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

postman collection run

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

You can find the collection ID in Postman. First, select Collections in the sidebar and select a collection. Then select the information icon Information icon in the right sidebar to access the collection ID.


--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-unicodeReplaces all symbols in the output with their plain text equivalents.
--environment [UID] or [file-path], -eSpecifies 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], -gSpecifies 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.
--iteration-count [number], -nSpecifies the number of times the collection will run when used in conjunction with the iteration data file.
--iteration-data [file-path] or [URL], -dSpecifies 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-redirectsPrevents the Postman CLI from automatically following 3XX redirect responses.
--insecure, -kTurns off SSL verification checks and enables self-signed SSL certificates.
--no-insecure-file-readPrevents reading of files situated outside of the working directory.
--silentTurns off terminal output.
--ssl-client-cert-list <path>Specify the path to a client certificates configurations (JSON)
--ssl-client-cert <path>Specify the path to a client certificate (PEM)
--ssl-client-key <path>Specify the path to a client certificate private key
--ssl-client-passphrase <passphrase>Specify the client certificate passphrase (for protected key)
--ssl-extra-ca-certs <path>Specify additional trusted CA certificates (PEM)
--suppress-exit-code, -xSpecify 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 execution.
--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 execution. The default is 0.
--verboseShows detailed information of 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.


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 your 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. api lint shows a warning if 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.


--fail-severity [severity], -fTriggers an exit failure code for rule violations at or above the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARN, and ERROR (default).
--suppress-exit-code, -xSpecifies whether to override the default exit code for the current run.


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

Publishing an API version

You can publish API versions from the command line with the Postman CLI. This enables you 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 will be 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 and provide paths to the schema directory and collection paths instead of IDs.


--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-pollSpecifies not to poll for completion status of the publish action.
--suppress-exit-code, -xSpecifies 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.

Last modified: 2024/05/07