Postman CLI

Postman CLI is the official command-line tool from Postman. It runs collections from a terminal, signs in to your Postman account, and sends results back to the Postman cloud. Teams use it in automated pipelines where no one clicks buttons.

The Remote Control Picture

A television has buttons on its body, yet most people use a remote control. The Postman app is the television body. The CLI is the remote: it triggers the same collections from a keyboard command or from an automation server.

  POSTMAN APP (clicks)           POSTMAN CLI (commands)
  ────────────────────           ──────────────────────
  Open collection                postman collection run <id>
  Choose environment             --environment <id>
  Click Run                      (press Enter)
  Read results on screen         Read results in terminal and cloud

Postman CLI and Newman Compared

Aspect	Postman CLI	Newman
Maintained by	Postman	Postman, as an open-source project
Account sign-in	Yes, through an API key	Not required
Collection source	Cloud ID or local file	Local file or URL
Results	Terminal output plus cloud run history	Terminal output and reporter files
Extra checks	Supports governance and security features on eligible plans	Focused on running collections

Both tools run collections successfully. Choose Postman CLI when you want results stored in your account, and choose Newman when you need a lightweight open-source runner.

Install the CLI

Postman publishes installers for Windows, macOS, and Linux. Open the Postman documentation, copy the install command for your operating system, and run it in a terminal. Confirm the installation with:

postman --version

Create an API Key

1. Open your Postman account settings in the app or on the website.
2. Select API keys.
3. Click Generate API Key and name it, for example build-server.
4. Copy the key immediately and store it in a password manager.

The key grants access to your account. Treat it like a password and never commit it to a code repository.

Sign In

postman login --with-api-key YOUR_API_KEY

Automation servers store the key as a secret variable and pass it to the command, so the key never appears in the script text.

Run a Collection

postman collection run 12345678-abcd-1234-abcd-1234567890ab

The long value is the collection ID. Find it in the app: open the collection, click the Info icon in the right sidebar, and copy the ID. Add an environment with its own ID:

postman collection run COLLECTION_ID -e ENVIRONMENT_ID

Run a local exported file instead of a cloud collection by giving the file path:

postman collection run ./shop-collection.json

Useful Options

Option	Purpose
-e, --environment	Select an environment
-d, --iteration-data	Supply a CSV or JSON data file
-n, --iteration-count	Repeat the run a set number of times
--bail	Stop at the first failure
--timeout-request	Limit the wait for each request

Run postman collection run --help to see the complete list for your installed version. Options change between releases.

Read the Results

The terminal prints each request with its status code, response time, and test results. A summary table at the end counts passed and failed assertions. The command ends with a non-zero exit code when a check fails, and automation servers use that code to mark a build as broken.

  Command runs
       │
       ├── All tests pass ──► exit code 0 ──► pipeline continues
       └── Any test fails ──► exit code 1 ──► pipeline stops

Sample Pipeline Step

steps:
  - name: Run API tests
    run: |
      postman login --with-api-key "$POSTMAN_API_KEY"
      postman collection run "$COLLECTION_ID" -e "$ENVIRONMENT_ID"

Replace the placeholder variables with secrets stored in your automation platform.

Good Habits

• Create a separate API key for each automation server.
• Rotate keys on a regular schedule and delete unused ones.
• Keep production secrets out of shared environments.
• Pin the CLI version in pipelines so updates never surprise you.

Key Points

• Postman CLI runs collections from the terminal and records results in your account.
• An API key signs the CLI in without a browser.
• The collection run command accepts cloud IDs or local files.
• Exit codes tell automation servers whether tests passed.
• Newman remains a good open-source alternative.