Newman: running Postman collections from the command line

The gap Newman fills between Postman and a build agent

Postman is a desktop application. A collection built there is a JSON document describing requests, folders, variables and test scripts. That document is convenient to author but awkward to schedule: a build agent has no GUI, and clicking Send by hand does not produce a pass or fail signal a pipeline can read.

Newman closes that gap. The README describes it as "a command-line collection runner for Postman" that runs a collection directly from the command line, and it is explicit about the intended audience: it is "built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems." The repository topics list ci and jenkins alongside api-testing, which matches that framing.

The person this is for is an engineer who already writes requests and assertions in Postman and wants those assertions to gate a merge. It is not a general-purpose HTTP client, and it does not generate tests. Its input is a collection that someone else authored.

What actually happens during a newman run

The execution path is visible in package.json. Newman is a thin CLI and library layer over three Postman packages: postman-collection for the collection object model, postman-collection-transformer for converting older collection formats, and postman-runtime for executing requests. The bin entry maps the newman command to ./bin/newman.js, and index.js is the library entry point, so the CLI and the programmatic API share the same runner.

That layering explains several behaviours. Because the transformer is a dependency, older collection exports are converted rather than rejected. Because the runtime does the work, environment variables, globals and iteration data all resolve the way they do in the app. And because the collection object model comes from postman-collection, Newman does not invent a second file format.

A run produces a summary object and emits events. The README documents a run summary object and a list of events emitted during a collection run, and the library example passes a callback that receives an error. Reporters consume that same stream, which is why a custom reporter can be written without touching the runner.

Installing Newman and running a first collection

Newman requires Node.js >= v16, per the Getting started section. The README calls npm the easiest route and notes that installing globally lets you run it from anywhere.

npm install -g newman

Homebrew is the documented alternative for macOS users.

brew install newman

Before running anything you need a collection file. The README says to export your Postman Collection as a JSON file from the Postman App. Then point newman run at it:

newman run examples/sample-collection.json

The repository ships examples/sample-collection.json, so that exact command works from a clone. Newman also accepts a URL in place of a path, which the README illustrates with a getpostman.com collection link.

Reporters are the first option most people touch. The CLI reporter is on by default, but the README warns that enabling any other reporter suppresses CLI output unless you list cli explicitly:

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

The inbuilt reporter names are cli, json, junit, progress and emojitrain. For an environment file, the flag is -e or --environment, and for a data file it is -d or --iteration-data.

Where Newman stops being the right tool

Newman runs collections. It does not create them, edit them, or check them into a useful diff. If your team does not use Postman, the value proposition collapses: you would be authoring JSON by hand to feed a runner whose entire convenience comes from the editor that produces that JSON.

The reporter behaviour is a second sharp edge. The README's own note that adding a reporter silently removes CLI output trips people up in CI logs, where an empty console looks like a hung job rather than a misconfigured flag. If your pipeline expects human-readable progress and you enabled junit, you get the XML and nothing else.

Version compatibility is a third constraint worth checking before you standardise. The README documents a compatibility section and a migration guide, and the dependency list pins specific versions of postman-runtime and postman-collection. A collection that relies on newer Postman features may not behave identically under an older Newman pin, and the README does not promise forward compatibility with every collection feature.

Finally, Newman has no scheduler, no result database and no history. It runs once and exits. Anything that resembles trend analysis has to be built on top of the JSON or JUnit output.

Newman as a library instead of a binary

The README states that the entire set of CLI functionality is available programmatically, and index.js is the module entry point. The documented example requires newman and calls newman.run with an options object containing a collection and a reporters value, then handles an error in the callback.

The difference from the CLI is where the orchestration lives. Instead of shelling out and parsing exit codes, you get the run summary object and the emitted events in process. The examples directory leans into this: examples/parallel-collection-runs.js, examples/run-collections-in-directory.js, examples/find-unique-urls-in-run.js and examples/read-collection-from-file.js all describe things the CLI does not do out of the box. Running collections in a directory, in parallel, or inspecting the URLs touched during a run are library-level concerns.

That is the honest trade-off. The CLI is a fixed surface with a documented option list. The library is open-ended but you own the error handling, the concurrency and the reporting glue.

How Newman compares with a code-first HTTP test suite

The nearest alternative in practice is a code-first HTTP test library in the language your application is already written in, where requests and assertions are source files reviewed like any other code. The difference is not speed or coverage; it is where the test definition lives.

With Newman, the definition lives in a Postman collection, a JSON artifact that non-engineers can open in the app, that carries folders and saved examples, and that can be exported and shared as a file or a link. With a code-first suite, the definition lives in the repository next to the code it exercises, and reviewers see changes as a diff in the same pull request.

Newman's advantage is the editor and the shared vocabulary it gives QA and backend engineers. Its cost is the export step and the fact that a collection is generated output rather than hand-maintained source. Teams that already have a Postman workspace gain a lot from Newman; teams that do not are usually better served by writing the tests where the code is.

Maintenance, licensing and what to check before standardising

The repository is not archived, and the last push was on 2026-09-18, which is recent. The version in package.json is 6.2.2. The project is licensed Apache-2.0, which permits commercial and private use and requires that the licence and notices be preserved; the LICENSE.md file at the repository root carries the terms. That is a description of the licence text, not legal advice, and anyone redistributing Newman inside a product should read LICENSE.md rather than rely on this summary.

Upgrade cost is mostly about the pinned Postman packages. Newman depends on postman-runtime, postman-collection and postman-collection-transformer at specific versions, so a Newman upgrade can move the runtime behaviour underneath your existing collections. The repository ships a MIGRATION.md file and a compatibility section in the README, which is where breaking changes are documented. There is also a CHANGELOG.yaml at the root, and the package.json release script points at npm/create-release.js.

One practical gap: the README documents installation, options, reporters and the library API, but it does not document a rollback procedure for a collection that regresses after an upgrade. Pinning the Newman version in your CI image is the obvious mitigation, and that is a decision you make outside Newman itself.

Editorial conclusion

Adopt Newman if your tests already live in Postman and you want the same collection to run on a build agent; the export step is the only real friction. Do not adopt it if you have no Postman collection and no intention of writing one, because Newman runs collections and nothing else. Before committing, verify that your Node.js version is at least v16, that the collection exports cleanly, and which reporter your CI system can actually parse.

Frequently asked questions

Official sources

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