Newman — Run Postman API Collections from the Command Line

Introduction

Newman is the official command-line companion for Postman that lets you run Postman collections outside the Postman app. It executes every request in a collection, runs the associated pre-request scripts and test assertions, and reports pass/fail results to stdout or external reporters. This bridges the gap between interactive API design in Postman and automated regression testing in CI/CD pipelines.

What Newman Does

• Executes Postman collections including requests, folders, pre-request scripts, and tests
• Supports environment and global variable files for multi-stage deployments
• Generates reports via built-in CLI reporter and community plugins (HTML, JUnit, JSON)
• Runs collections from local files, URLs, or the Postman API
• Returns non-zero exit codes on test failures for CI/CD gate integration

Architecture Overview

Newman loads a Postman collection JSON file and iterates through its items in the defined order. For each request, it resolves variables from the environment and globals, executes pre-request scripts in a sandboxed JavaScript runtime, sends the HTTP request, and then runs the test scripts against the response. Results are accumulated and passed to one or more reporter plugins. The entire flow is orchestrated by the Postman Runtime SDK, which handles cookie jars, authentication helpers, and request chaining.

Self-Hosting & Configuration

• Install globally via npm install -g newman or as a project dependency
• Export collections from Postman as JSON v2.1 files for version control
• Pass environment files with -e env.json and globals with -g globals.json
• Install reporter plugins: npm install -g newman-reporter-htmlextra
• Use --delay-request to add pauses between requests for rate-limited APIs

Key Features

• Full Postman collection execution including scripts, tests, and variable resolution
• Extensible reporter system with community plugins for HTML, JUnit, Allure, and more
• Supports collection iteration with --iteration-count and CSV/JSON data files
• Works with Postman's authentication helpers: OAuth2, Bearer, Basic, Digest, AWS Sig v4
• Programmatic Node.js API for embedding collection runs in custom tooling

Comparison with Similar Tools

• Postman (GUI) — interactive API design; Newman brings the same collections to the terminal and CI
• Bruno — open-source API client with its own CLI runner; Newman leverages the existing Postman ecosystem
• Hoppscotch CLI — lightweight open-source API testing; Newman supports richer scripting and auth helpers
• Insomnia Inso — CLI companion for Insomnia; Newman has a larger plugin ecosystem
• HTTPie CLI — excellent for ad-hoc requests; Newman runs scripted test suites with assertions

FAQ

Q: Can I run a single request from a collection? A: Yes. Use --folder "folder name" to run a specific folder, or filter via the programmatic API for individual requests.

Q: How do I pass secrets without hardcoding them? A: Use environment files with placeholder values and override them via --env-var "key=value" from CI secrets.

Q: Does Newman support file uploads in requests? A: Yes. Reference files in form-data fields using the src property in the collection JSON, and ensure the files are available at the specified paths.

Q: How do I get JUnit reports for CI integration? A: Install newman-reporter-junitfull and run with -r junitfull --reporter-junitfull-export results.xml.

Sources

• https://github.com/postmanlabs/newman
• https://learning.postman.com/docs/collections/using-newman-cli/command-line-integration-with-newman/