What Is Newman?
Newman is Postman's official command-line collection runner, distributed as a Node.js/npm package. It takes an exported collection JSON (or a collection fetched directly from the Postman API) and executes it exactly the way Collection Runner would inside the desktop app, but entirely from a terminal — making it the bridge between Postman's GUI-based testing and automated, scriptable environments like CI servers.
Cricket analogy: Newman is like a scoring app a curator uses to replay an entire match's ball-by-ball data from a scoresheet file without needing the stadium's live broadcast setup, just the raw data and a terminal.
Installing and Running a Collection
After installing Newman globally with npm, running newman run collection.json executes the collection with the same core options as Collection Runner: -e for an environment file, -g for globals, -d for a data file, -n for iteration count, and --delay-request for pacing between requests. Every flag maps directly to a setting you'd otherwise configure through the desktop UI.
Cricket analogy: Running "newman run collection.json -e env.json" is like handing the umpire both the match rulebook and the day's team sheet before the first ball, so every decision uses the right context from the start.
npm install -g newman
newman run collection.json \
-e staging.postman_environment.json \
-d data/users.csv \
--reporters cli,htmlextra \
--reporter-htmlextra-export report.htmlNewman Reporters
The --reporters flag controls how Newman presents results, and multiple reporters can run in the same invocation. The built-in cli reporter prints a readable summary to stdout, json exports a full machine-readable results file, junit produces XML suited to CI test dashboards, and the popular community reporter htmlextra generates a rich standalone HTML report with charts and request/response detail.
Cricket analogy: Choosing "--reporters cli,htmlextra" is like a broadcaster running both the stadium's live commentary feed and a printed scorecard simultaneously, giving different audiences the format they need.
Exit Codes and Scripting Around Newman
Newman returns exit code 0 when every test assertion passes and a non-zero exit code the moment any assertion fails, distinct from an internal Newman error (like a missing file). Shell scripts and CI systems check this exit code (commonly via $? in bash) to decide whether to proceed to the next pipeline stage or halt and report failure.
Cricket analogy: Newman's non-zero exit code on failed tests is like the third umpire flashing a red light that stops play immediately, forcing the whole match to be reviewed before continuing.
Newman accepts a Postman Collection either as a local file path or directly as a Postman API collection UID/URL with --postman-api-key, so CI runners never need to check exported JSON into the repo.
The default 'cli' reporter only prints to stdout — if you don't add --reporters json or --reporter-json-export, you'll have no machine-readable artifact for later analysis or dashboarding.
- Newman is the official command-line collection runner for Postman, installable as an npm package (npm install -g newman).
- newman run <collection.json> executes a collection headlessly, supporting the same -e (environment), -g (globals), and -d (data file) options as Collection Runner.
- --reporters selects one or more output formats (cli, json, junit, htmlextra) that can run simultaneously.
- Newman exits with a non-zero status code if any test assertion fails, making it easy to gate CI steps.
- htmlextra (a community reporter) generates a rich standalone HTML report suitable for build artifacts.
- Newman can pull collections/environments directly from the Postman API instead of requiring exported JSON files in the repo.
Practice what you learned
1. How do you install Newman?
2. What does a non-zero Newman exit code indicate?
3. Which flag lets Newman produce both a console summary and a standalone HTML report in one run?
4. What is the purpose of the -d flag in a newman run command?
Was this page helpful?
You May Also Like
Collection Runner
Learn how Postman's Collection Runner executes an entire collection of requests in sequence, complete with data-driven iterations, delays, and detailed pass/fail reporting.
Postman/Newman in CI/CD Pipelines
Integrating Postman collections into CI/CD pipelines via Newman lets teams catch API regressions automatically on every commit, before code reaches production.
Monitors and Scheduled Runs
Postman Monitors run your collections automatically on a schedule from multiple regions, alerting you the moment an API starts failing or slowing down in production.