Postman Newman CLI

Newman is Postman's command-line tool. It runs Postman collections from a terminal without opening the Postman app. Newman makes it possible to include API tests in automated build pipelines, scheduled scripts, and CI/CD systems where a graphical interface is not available.

Why Newman Exists

The Postman desktop app is designed for humans. Servers and build pipelines have no screen. Newman bridges this gap — it takes your exported Postman collection and runs every request and test automatically from the command line, then exits with a result code.

Developer's laptop (Postman app):
  Create requests → Write tests → Export collection

Build server (Newman):
  newman run collection.json --environment env.json
  → Runs all requests
  → Runs all tests
  → Prints pass/fail report
  → Exits with code 0 (all pass) or 1 (any fail)

Install Newman

Newman requires Node.js version 16 or higher. Install it first from nodejs.org.

Then install Newman globally using npm:

npm install -g newman

Confirm the installation:

newman --version

You should see a version number printed. Newman is ready.

Export Your Collection from Postman

Right-click your collection in the Postman sidebar
Select Export
Choose Collection v2.1
Save the file as my-collection.json

Do the same for your environment:

Go to the Environments tab
Click the three-dot menu on the environment
Select Export
Save as my-environment.json

Run a Collection with Newman

Open a terminal, navigate to the folder containing your JSON files, and run:

newman run my-collection.json

Newman executes every request and prints results to the terminal. To include an environment file:

newman run my-collection.json --environment my-environment.json

Reading Newman's Terminal Output

newman

My API Collection

→ GET All Users
  GET https://jsonplaceholder.typicode.com/users [200 OK, 245ms]
  ✔ Status is 200
  ✔ Response has users array

→ GET User by ID
  GET https://jsonplaceholder.typicode.com/users/1 [200 OK, 189ms]
  ✔ User ID is 1
  ✔ Name is a string

→ POST Create User
  POST https://jsonplaceholder.typicode.com/users [500 Internal Server Error, 311ms]
  ✗ Status is 201 | AssertionError: expected response to have status 201 but got 500

┌─────────────────────────┬──────────┬────────────┐
│                         │ executed │   failed   │
├─────────────────────────┼──────────┼────────────┤
│          iterations     │        1 │          0 │
│            requests     │        3 │          0 │
│        test-scripts     │        3 │          0 │
│          assertions     │        7 │          1 │
│total run duration: 745ms|          |            │
└─────────────────────────┴──────────┴────────────┘

A green checkmark means the test passed. A red cross means a test failed. The summary table at the bottom shows totals. Newman exits with code 1 when any assertion fails — this is how CI/CD systems detect test failures.

Useful Newman Flags

Flag	What It Does	Example
--environment	Load an environment file	--environment prod-env.json
--iteration-count	Number of times to repeat the collection	--iteration-count 5
--iteration-data	Load a CSV or JSON data file	--iteration-data users.csv
--delay-request	Milliseconds to wait between requests	--delay-request 200
--timeout	Maximum time for the whole run in ms	--timeout 60000
--bail	Stop running if any test fails	--bail
--folder	Run only a specific folder in the collection	--folder "Authentication"
--reporters	Output format for results	--reporters cli,json

Generate Reports

Newman can produce HTML reports using the newman-reporter-htmlextra package. Install it first:

npm install -g newman-reporter-htmlextra

Then run Newman with the HTML reporter:

newman run my-collection.json \
  --environment my-environment.json \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export report.html

Newman creates a report.html file you can open in any browser. It shows a detailed breakdown of every request, test, and assertion with colour-coded results.

Run Newman with a Postman API Link

Instead of exporting files, you can pass a collection URL from the Postman API directly to Newman:

newman run https://api.postman.com/collections/your-collection-id?apikey=your-postman-api-key

This always runs the latest version of the collection without re-exporting. Get your Postman API key from postman.com → Settings → API keys.

Exit Codes

Exit Code	Meaning
0	All requests and tests passed
1	One or more tests failed
other	Newman encountered an error (bad file path, network error, etc.)

CI/CD systems read the exit code automatically to decide whether a build passes or fails.

Summary

Newman runs Postman collections from the command line without any graphical interface. Install it via npm, export your collection and environment as JSON files, then run newman run. Results print to the terminal with pass/fail indicators. Newman exits with code 0 on success and 1 on failure, making it easy to plug into any automated pipeline or build system.

Previous lessons

Back to courses

Next lessons