Newman runs Postman collections from the command line

Maintenance mode, and a pointer to a different binary

Right after describing Newman, the README promotes a different tool: the Postman CLI, which it says lets you run collections, automate tests, integrate API checks into CI/CD pipelines and enforce quality gates, installed with npm install -g postman-cli. That pointer is written by the people who own both tools. Commits still arrive: the default branch is develop and the last push was on 2026-10-09.

One global install, one collection file, Node 16 as the floor

Node.js v16 or newer is the only stated prerequisite, and the shortest path is a single npm command. It installs the package globally so the binary resolves from any directory; drop the `-g` flag for a local install inside a project instead. Homebrew is offered as the second route. package.json declares preferGlobal and maps the binary to ./bin/newman.js, with index.js as the module entry point, so a global install is the intended shape rather than an accident. The first real use needs a collection exported as JSON from the Postman app:

$ npm install -g newman

Point the runner at that file and it executes the collection, resolving variables as it goes:

$ newman run examples/sample-collection.json

A collection hosted on the Cloud API service is handled the same way, because the runner fetches a file given as a URL:

$ newman run https://www.getpostman.com/collections/631643-f695cab7-6878-eb55-7943-ad88e1ccfd65-JsLv

What lands in the terminal comes from the cli reporter, which is on by default when Newman runs as a command. Where that default stops applying is the subject of the next section.

Adding a reporter turns off the terminal output

Reporters are chosen with `-r` or `--reporters`, and five are built in: `cli`, `json`, `junit`, `progress` and `emojitrain`. The trap is stated plainly in the usage notes: enabling one or more of the others results in no CLI output. Since `cli` is what makes the terminal talk, a job that asks for machine-readable output can end up printing nothing at all, and an empty log reads a lot like a run that passed quietly:

$ newman run examples/sample-collection.json -r cli,json

Naming `cli` next to `json` is the fix, and it costs nothing. For a CI pipeline the one worth wiring into a test reporting tool is `junit`, which produces XML. The page also carries an HTML Reporter section and an External Reporters section on creating your own reporter, so those five names are not the whole output surface.

Environment variables outrank globals, and -n needs a data file

Three flags decide what a collection resolves at run time, and they do not treat equal names equally. `-e` or `--environment` takes an environment file path or URL, and an environment supplies the set of variables a collection can use. `-g` or `--globals` takes a similar file for global variables, described as similar but of lower precedence, where an environment variable of the same name overrides it. So a globals file holding `base_url` and an environment also holding `base_url` sends every request to the environment's host, with no error and no warning. That is the failure to watch when a suite passes locally and fails in CI, or passes against the wrong service entirely. `-d` or `--iteration-data` takes a JSON or CSV data file, by path or as a URL, and `-n` or `--iteration-count` sets how many times the collection runs with it. The count is defined in conjunction with that data file, so `-n` on its own has nothing to iterate over. `--folder` narrows a run to particular folders or specific requests and takes repeated values.

Pinned Postman forks decide what a collection can do

The dependency list in package.json says more about behaviour than the feature prose does. Two Postman packages carry plain versions: postman-collection 4.4.0 for the collection model and postman-runtime 7.39.1 for the engine that executes it. Two more are forks, marked by a suffix on the version itself: @postman/tough-cookie 4.1.3-postman.1 and postman-request 2.88.1-postman.48. When a request behaves differently from a stock Node HTTP client, the cookie jar and the HTTP layer are where to look. Around them sit the pieces that explain the terminal: commander 11.1.0 parses the flags, cli-progress 3.12.0 draws the bar, cli-table3 0.6.5 lays out the table, colors 1.4.0 paints it, and filesize 10.1.4 with pretty-ms 7.0.1 format sizes and durations. csv-parse 4.16.3 is what makes the CSV form of iteration data work, and chardet 2.0.0 guesses character sets. Every version is written out in full rather than as a range, so nothing drifts between two installs of the same Newman release.

examples/ carries the shapes a CI job actually needs

The API surface is small: newman.run takes an options object and a callback, and returns a run event emitter. The callback receives an error and a run summary object, while the emitter carries the events emitted during a collection run. For a JavaScript project that means the CLI's behaviour is reachable without a shell:

const newman = require('newman'); // require newman in your project

// call newman.run to pass `options` object and wait for callback
newman.run({
    collection: require('./sample-collection.json'),
    reporters: 'cli'
}, function (err) {
	if (err) { throw err; }
    console.log('collection run complete!');
});

examples/ holds the harder shapes. parallel-collection-runs.js answers how to run several collections at once, run-collections-in-directory.js answers how to sweep a directory instead of naming files, find-unique-urls-in-run.js pulls the URLs back out of a finished run, and read-collection-from-file.js covers loading a collection off disk. Two filenames answer a compatibility question: v1.postman_collection.json is a version 1 collection, and postman-collection-transformer 4.1.8 is the dependency that converts it into something current code can run. ssl-client-cert-list.json pairs with the SSL section, where client certificates are supplied as a list.

No GitHub releases means no release feed to watch

There are no GitHub releases for this project. The version lives in package.json, which reads 6.2.3, and that same file is what `-v` and `--version` print. Upgrades are therefore something you notice in the npm registry rather than on a release page, and a CI job that pins a version has no feed to subscribe to. The repository root does carry CHANGELOG.yaml and MIGRATION.md, and the table of contents gives the Migration Guide its own section, so the upgrade story is written as files you have to go and read. The consequence for a long-lived pipeline is that the timing of a breaking change is not announced anywhere a build system can watch. Licence-wise the package is Apache-2.0, and LICENSE.md sits at the root next to SECURITY.md. The table of contents also covers proxy and SOCKS configuration, file uploads, and running against the Postman API, each as its own escape hatch rather than a flag on the main command.

Editorial conclusion

Newman still fits teams whose collections are stable and whose pipelines already read its cli, json or junit output, and the library form is the cleaner route when the run is already inside a Node script. It is the wrong choice for a collection that needs whatever Postman shipped most recently, because its Postman runtime packages are pinned to exact versions. Check three things before wiring it into a job: that Node.js is v16 or newer on the runner, that adding your reporter still names cli so the log is not empty, and that any variable shared between your globals file and your environment resolves to the value you meant.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. postmanlabs/newman on GitHub
4. Project website
5. README