Automation Academy
API Automation
Newman CLI

Newman CLI: Running Postman Collections in CI/CD Pipelines

Parul Dhingra - Senior Quality Analyst
Parul Dhingra13+ Years ExperienceHire Me

Senior Quality Analyst

Updated: 1/23/2026

Postman is excellent for manual API testing and development, but its real power emerges when you integrate collections into automated workflows. Newman is Postman's command-line companion that runs collections anywhere - on your local machine, in CI/CD pipelines, or as part of scheduled monitoring jobs.

This guide covers Newman from installation to advanced CI/CD integration patterns.

What is Newman?

Newman is a command-line collection runner for Postman. It allows you to:

  • Run Postman collections without the GUI
  • Integrate API tests into CI/CD pipelines
  • Generate test reports in various formats
  • Run collections with different environments
  • Execute data-driven tests from CSV/JSON files

Why Newman?

  • Automated testing in pipelines
  • Scheduled API monitoring
  • Parallel execution across environments
  • Consistent test execution in different environments

Installation

Using npm (Recommended)

# Global installation
npm install -g newman
 
# Verify installation
newman --version
 
# Local project installation
npm install --save-dev newman

Using Docker

# Pull the image
docker pull postman/newman
 
# Run a collection
docker run -v /path/to/collections:/etc/newman -t postman/newman \
    run collection.json

Installing Reporters

# HTML reporter
npm install -g newman-reporter-htmlextra
 
# JUnit reporter (for CI systems)
npm install -g newman-reporter-junit
 
# CLI progress reporter
npm install -g newman-reporter-progress

Basic Usage

Running a Collection

# Run from exported file
newman run collection.json
 
# Run from Postman API URL
newman run https://api.postman.com/collections/YOUR_COLLECTION_ID?apikey=YOUR_API_KEY
 
# Run specific folder
newman run collection.json --folder "Authentication"

Exporting from Postman

  1. Open Postman
  2. Click ... on your collection
  3. Select Export
  4. Choose Collection v2.1 format
  5. Save as JSON

For collections shared via Postman API, get the URL from Collection → Share → Via API. You'll need your Postman API key.

Command Line Options

Essential Options

OptionDescriptionExample
-e, --environmentEnvironment file-e dev.json
-g, --globalsGlobal variables file-g globals.json
-d, --iteration-dataData file (CSV/JSON)-d data.csv
-n, --iteration-countNumber of iterations-n 5
--folderRun specific folder--folder "Users"
--delay-requestDelay between requests (ms)--delay-request 1000
-r, --reportersOutput reporters-r cli,html
--bailStop on first failure--bail
--timeoutRequest timeout (ms)--timeout 10000

Complete Command Example

newman run collection.json \
    --environment production.json \
    --globals globals.json \
    --iteration-data testdata.csv \
    --iteration-count 3 \
    --delay-request 500 \
    --reporters cli,htmlextra,junit \
    --reporter-htmlextra-export reports/report.html \
    --reporter-junit-export reports/junit.xml \
    --timeout-request 30000 \
    --bail

Timeout Options

# Global timeout for entire run
--timeout 300000
 
# Per-request timeout
--timeout-request 30000
 
# Per-script timeout
--timeout-script 5000

Environments and Variables

Using Environment Files

Export environment from Postman, then:

newman run collection.json -e development.json
newman run collection.json -e staging.json
newman run collection.json -e production.json

Global Variables

newman run collection.json \
    -e environment.json \
    -g globals.json

Runtime Variables

Override variables from command line:

newman run collection.json \
    --env-var "baseUrl=https://api.example.com" \
    --env-var "apiKey=secret123"

Environment File Structure

{
  "id": "env-id",
  "name": "Development",
  "values": [
    {
      "key": "baseUrl",
      "value": "https://dev-api.example.com",
      "type": "default",
      "enabled": true
    },
    {
      "key": "apiKey",
      "value": "dev-key-123",
      "type": "secret",
      "enabled": true
    }
  ]
}

Reporters

Built-in Reporters

# CLI reporter (default)
newman run collection.json -r cli
 
# JSON reporter
newman run collection.json -r json --reporter-json-export results.json
 
# JUnit reporter
newman run collection.json -r junit --reporter-junit-export junit.xml

HTML Extra Reporter

The most popular HTML reporter with enhanced features:

npm install -g newman-reporter-htmlextra
 
newman run collection.json \
    -r htmlextra \
    --reporter-htmlextra-export report.html \
    --reporter-htmlextra-darkTheme \
    --reporter-htmlextra-title "API Test Results" \
    --reporter-htmlextra-browserTitle "API Tests"

Multiple Reporters

newman run collection.json \
    -r cli,htmlextra,junit \
    --reporter-htmlextra-export reports/html/report.html \
    --reporter-junit-export reports/junit/results.xml

Custom Reporter Options

# HTML Extra options
--reporter-htmlextra-export <path>
--reporter-htmlextra-darkTheme
--reporter-htmlextra-testPaging
--reporter-htmlextra-showEnvironmentData
--reporter-htmlextra-skipHeaders
--reporter-htmlextra-omitResponseBodies
 
# JUnit options
--reporter-junit-export <path>

CI/CD Integration

GitHub Actions

name: API Tests
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 6 * * *' # Daily at 6 AM
 
jobs:
  api-tests:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Newman
        run: |
          npm install -g newman
          npm install -g newman-reporter-htmlextra
 
      - name: Run API Tests
        run: |
          newman run tests/collection.json \
            -e tests/environments/${{ github.ref_name == 'main' && 'production' || 'staging' }}.json \
            -r cli,htmlextra,junit \
            --reporter-htmlextra-export reports/report.html \
            --reporter-junit-export reports/junit.xml \
            --bail
 
      - name: Upload Test Results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: reports/
 
      - name: Publish Test Results
        uses: dorny/test-reporter@v1
        if: always()
        with:
          name: API Test Results
          path: reports/junit.xml
          reporter: java-junit

Jenkins Pipeline

pipeline {
    agent any
 
    environment {
        NEWMAN_VERSION = '6.0.0'
    }
 
    stages {
        stage('Setup') {
            steps {
                sh 'npm install -g newman@${NEWMAN_VERSION}'
                sh 'npm install -g newman-reporter-htmlextra'
            }
        }
 
        stage('API Tests') {
            steps {
                sh '''
                    newman run tests/collection.json \
                        -e tests/environments/${ENVIRONMENT}.json \
                        -r cli,htmlextra,junit \
                        --reporter-htmlextra-export reports/report.html \
                        --reporter-junit-export reports/junit.xml
                '''
            }
        }
 
        stage('Publish Results') {
            steps {
                junit 'reports/junit.xml'
                publishHTML([
                    allowMissing: false,
                    alwaysLinkToLastBuild: true,
                    keepAll: true,
                    reportDir: 'reports',
                    reportFiles: 'report.html',
                    reportName: 'API Test Report'
                ])
            }
        }
    }
 
    post {
        always {
            archiveArtifacts artifacts: 'reports/**', fingerprint: true
        }
        failure {
            mail to: 'team@example.com',
                 subject: "API Tests Failed: ${env.JOB_NAME}",
                 body: "Check console output at ${env.BUILD_URL}"
        }
    }
}

GitLab CI

stages:
  - test
 
api_tests:
  stage: test
  image: node:20
 
  before_script:
    - npm install -g newman newman-reporter-htmlextra
 
  script:
    - |
      newman run tests/collection.json \
        -e tests/environments/${CI_ENVIRONMENT_NAME:-staging}.json \
        -r cli,htmlextra,junit \
        --reporter-htmlextra-export reports/report.html \
        --reporter-junit-export reports/junit.xml
 
  artifacts:
    when: always
    paths:
      - reports/
    reports:
      junit: reports/junit.xml
 
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

Azure DevOps

trigger:
  - main
  - develop
 
pool:
  vmImage: 'ubuntu-latest'
 
steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
 
  - script: |
      npm install -g newman newman-reporter-htmlextra
    displayName: 'Install Newman'
 
  - script: |
      newman run tests/collection.json \
        -e tests/environments/$(Environment).json \
        -r cli,htmlextra,junit \
        --reporter-htmlextra-export $(Build.ArtifactStagingDirectory)/report.html \
        --reporter-junit-export $(Build.ArtifactStagingDirectory)/junit.xml
    displayName: 'Run API Tests'
 
  - task: PublishTestResults@2
    inputs:
      testResultsFormat: 'JUnit'
      testResultsFiles: '$(Build.ArtifactStagingDirectory)/junit.xml'
    condition: always()
 
  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: '$(Build.ArtifactStagingDirectory)'
      artifactName: 'test-results'
    condition: always()

Advanced Configuration

Using Newman as a Library

const newman = require('newman')
 
newman.run(
  {
    collection: require('./collection.json'),
    environment: require('./environment.json'),
    reporters: ['cli', 'htmlextra'],
    reporter: {
      htmlextra: {
        export: './reports/report.html',
        darkTheme: true,
      },
    },
    iterationCount: 1,
    bail: true,
  },
  (err, summary) => {
    if (err) throw err
 
    console.log('Collection run complete!')
    console.log(`Total tests: ${summary.run.stats.tests.total}`)
    console.log(`Failed tests: ${summary.run.stats.tests.failed}`)
 
    // Custom logic based on results
    if (summary.run.stats.tests.failed > 0) {
      process.exit(1)
    }
  },
)

Parallel Execution

const newman = require('newman')
const async = require('async')
 
const environments = ['dev', 'staging', 'prod']
 
async.parallel(
  environments.map((env) => {
    return function (callback) {
      newman.run(
        {
          collection: require('./collection.json'),
          environment: require(`./environments/${env}.json`),
          reporters: ['cli'],
        },
        callback,
      )
    }
  }),
  (err, results) => {
    if (err) console.error(err)
    console.log('All environments tested')
  },
)

Secure Secrets Handling

# Use environment variables
newman run collection.json \
    --env-var "apiKey=${API_KEY}" \
    --env-var "dbPassword=${DB_PASSWORD}"

In CI/CD:

# GitHub Actions
- name: Run Tests
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    newman run collection.json --env-var "apiKey=${API_KEY}"

Best Practices

Project Structure

api-tests/
├── collections/
│   ├── users-api.json
│   └── orders-api.json
├── environments/
│   ├── development.json
│   ├── staging.json
│   └── production.json
├── data/
│   └── test-users.csv
├── reports/           # Generated, gitignored
├── scripts/
│   └── run-tests.sh
├── package.json
└── README.md

Version Control

// package.json
{
  "scripts": {
    "test": "newman run collections/api.json -e environments/staging.json",
    "test:dev": "newman run collections/api.json -e environments/development.json",
    "test:prod": "newman run collections/api.json -e environments/production.json --bail",
    "test:report": "newman run collections/api.json -e environments/staging.json -r htmlextra --reporter-htmlextra-export reports/report.html"
  },
  "devDependencies": {
    "newman": "^6.0.0",
    "newman-reporter-htmlextra": "^1.23.0"
  }
}

Fail Fast in CI

newman run collection.json --bail

The --bail flag stops execution on first test failure, saving time in CI.

Troubleshooting

Common Issues

"Collection file not found"

# Check path is correct
ls -la collections/
# Use absolute path if needed
newman run "$(pwd)/collections/api.json"

"Environment variable not found"

# Ensure variable is exported
export API_KEY="secret"
newman run collection.json --env-var "apiKey=${API_KEY}"

"SSL certificate errors"

newman run collection.json --insecure

"Request timeout"

newman run collection.json --timeout-request 60000

Debug Mode

# Verbose output
newman run collection.json --verbose
 
# Show request bodies
newman run collection.json -r cli --reporter-cli-show-timestamps

Newman transforms Postman from a development tool into a production-grade testing solution. By integrating collections into CI/CD pipelines, you catch API regressions early and maintain confidence in your API's behavior across deployments.

Quiz on Newman CLI

Your Score: 0/10

Question: What is Newman in the context of Postman?

Continue Reading

Frequently Asked Questions (FAQs) / People Also Ask (PAA)

Can I run Newman without installing Node.js?

How do I handle sensitive data like API keys in Newman?

Can Newman run collections in parallel?

How do I get test results into my CI/CD dashboard?

What's the difference between --timeout and --timeout-request?

Can I use Postman's collection links directly with Newman?

How do I skip SSL certificate verification?

Can I add custom reporters to Newman?

Postman Complete GuideAPI Testing Strategies