Postman Newman CLI: Every Command and Option (2026)

Newman, the command-line runner for Postman collections, lets you automate your API testing and development workflows. It’s not just for running tests; it’s for integrating them seamlessly into your CI/CD pipelines, scripting complex request sequences, and generating detailed reports.

Here’s Newman in action, simulating a simple API call and checking a response:

# First, make sure you have Newman installed:
# npm install -g newman

# Export your Postman collection as a JSON file (e.g., my_collection.json)
# Export your Postman environment as a JSON file (e.g., my_environment.json)

# Run the collection using the CLI
newman run my_collection.json --environment my_environment.json

This command executes the requests defined in my_collection.json using the variables from my_environment.json. Newman will output the results to your terminal, indicating which requests passed and failed.

The Core Problem Newman Solves

Newman tackles the challenge of making API interactions repeatable, verifiable, and automated. Instead of manually clicking through Postman, you can spin up a collection of requests as part of a build process, a scheduled task, or a pre-deployment check. This ensures your API behaves as expected without human intervention, catching regressions early and providing confidence in your deployments.

How Newman Works Internally

At its heart, Newman parses your Postman collection JSON. It iterates through each request, meticulously populating it with variables from the specified environment (or global variables). For each request, it sends the HTTP request to the target API, captures the response, and then executes any associated pre-request scripts or test scripts. Pre-request scripts can dynamically alter the request (e.g., add headers, modify the body), while test scripts assert conditions on the response (e.g., check status codes, validate JSON payloads). Newman aggregates the results of all tests and provides a summary.

Key Commands and Options

The newman run command is your primary tool. Here’s a breakdown of its most useful options:

newman run <collection>: The most basic command. Runs a collection specified by its file path or a Postman API URL.
```
newman run ./path/to/your/collection.json
```
--environment <environment>: Specifies an environment to load variables from. This can be a file path or a Postman API URL.
```
newman run my_collection.json --environment ./my_env.json
```
--folder <folderName>: Runs only the requests within a specific folder in your collection.
```
newman run my_collection.json --folder "User Authentication"
```
--iteration-count <count>: Executes the entire collection a specified number of times. Useful for load testing or checking consistency.
```
newman run my_collection.json --iteration-count 5
```
--iteration-data <dataFile>: Runs the collection for each row in a CSV or JSON file. Each row becomes an iteration, with column headers/keys mapping to variable names.
```
# Example CSV data (data.csv):
# username,password
# testuser1,pass123
# testuser2,secure456

newman run my_collection.json --iteration-data data.csv
```
--delay <delay>: Introduces a delay (in milliseconds) between each request. Crucial for preventing API rate limiting or ensuring resources are available.
```
newman run my_collection.json --delay 500
```
--reporters <reporter1,reporter2,...>: Specifies which reporters to use. Common reporters include cli, json, html, junit.
```
newman run my_collection.json --reporters cli,junit --reporter-junit-export results.xml
```
--bail <on>: Exits the collection run immediately if an error occurs. on is the default, meaning it stops on the first error. off will run all iterations and requests regardless of errors.
```
newman run my_collection.json --bail off
```
--timeout <timeout>: Sets a global timeout (in milliseconds) for each request.
```
newman run my_collection.json --timeout 10000
```
--folder <folderName>: Runs only the requests within a specific folder in your collection.
```
newman run my_collection.json --folder "User Authentication"
```
--global-var <key=value>: Sets global variables directly from the command line.
```
newman run my_collection.json --global-var api_key=abcdef12345
```
--color <off|auto|always>: Controls color output. auto is the default, and it will enable colors if the terminal supports it.
```
newman run my_collection.json --color off
```
--verbose: Prints detailed information about each request and response. Invaluable for debugging.
```
newman run my_collection.json --verbose
```

The One Thing Most People Don’t Know

The --folder option can be used multiple times to run specific, non-contiguous folders. If you have folders named "Auth", "Users", and "Products", and you only want to run "Auth" and "Products", you can do newman run my_collection.json --folder "Auth" --folder "Products". This is incredibly useful for targeting specific parts of a large, complex collection without needing to create sub-collections or manually edit the JSON.

The next step is often integrating these runs into your CI/CD pipeline, which involves understanding how to capture and interpret the reporter outputs.