Postman CLI (newman) Cheatsheet¶

Installation¶

Platform	Command
npm (Global)	`npm install -g newman`
npm (Project)	`npm install --save-dev newman`
yarn (Global)	`yarn global add newman`
Ubuntu/Debian	`curl -fsSL https://deb.nodesource.com/setup_18.x \\| sudo -E bash -` `sudo apt-get install -y nodejs` `sudo npm install -g newman`
RHEL/CentOS/Fedora	`sudo dnf install nodejs npm` `sudo npm install -g newman`
macOS (Homebrew)	`brew install node` `npm install -g newman`
Windows (Chocolatey)	`choco install nodejs` `npm install -g newman`
Docker	`docker pull postman/newman`
Verify Installation	`newman --version`

Basic Commands¶

Command	Description
`newman run collection.json`	Run a Postman collection from local file
`newman run <collection-url>`	Run collection from URL (requires API key)
`newman run collection.json -e environment.json`	Run collection with environment variables
`newman run collection.json -g globals.json`	Run collection with global variables
`newman run collection.json -n 5`	Run collection with 5 iterations
`newman run collection.json -d data.csv`	Run with CSV data file (data-driven testing)
`newman run collection.json -d data.json`	Run with JSON data file
`newman run collection.json --folder "Auth Tests"`	Run specific folder from collection
`newman run collection.json --delay-request 2000`	Add 2000ms delay between requests
`newman run collection.json --timeout-request 10000`	Set 10 second request timeout
`newman run collection.json --insecure`	Disable SSL certificate verification
`newman run collection.json --bail`	Stop execution on first test failure
`newman run collection.json --verbose`	Show detailed execution information
`newman run collection.json --no-color`	Disable colored console output
`newman run collection.json --suppress-exit-code`	Always exit with code 0 (ignore failures)

Advanced Usage¶

Command	Description
`newman run collection.json -r cli,html,json`	Use multiple reporters simultaneously
`newman run collection.json -r html --reporter-html-export report.html`	Generate HTML report with custom filename
`newman run collection.json -r junit --reporter-junit-export junit.xml`	Generate JUnit XML report for CI/CD
`newman run collection.json --env-var "key=value"`	Override environment variable via CLI
`newman run collection.json --global-var "token=abc123"`	Set global variable via CLI
`newman run collection.json --export-environment env-out.json`	Export environment state after run
`newman run collection.json --export-globals globals-out.json`	Export global variables after run
`newman run collection.json --export-cookie-jar cookies.json`	Export cookies after collection run
`newman run collection.json --cookie-jar cookies.json`	Import cookies before collection run
`newman run collection.json --ssl-client-cert cert.pem --ssl-client-key key.pem`	Use client SSL certificates
`newman run collection.json --ssl-extra-ca-certs ca-bundle.pem`	Add custom CA certificates
`newman run collection.json --timeout-script 5000`	Set 5 second timeout for scripts
`newman run collection.json --ignore-redirects`	Don't follow HTTP redirects
`newman run collection.json --disable-unicode`	Disable Unicode in output
`newman run collection.json --working-dir /path/to/dir`	Set working directory for file operations
`newman run -x newman.json`	Run using configuration file
`docker run -v $(pwd):/etc/newman -t postman/newman run collection.json`	Run newman in Docker with volume mount

Configuration¶

Environment File Structure¶

{
  "id": "environment-id",
  "name": "Production Environment",
  "values": [
    {
      "key": "base_url",
      "value": "https://api.production.com",
      "enabled": true
    },
    {
      "key": "api_key",
      "value": "secret-key-123",
      "enabled": true,
      "type": "secret"
    },
    {
      "key": "timeout",
      "value": "5000",
      "enabled": true
    }
  ]
}

Global Variables File¶

{
  "id": "globals-id",
  "name": "Global Variables",
  "values": [
    {
      "key": "company_name",
      "value": "Acme Corp",
      "enabled": true
    },
    {
      "key": "api_version",
      "value": "v1",
      "enabled": true
    }
  ]
}

Newman Configuration File (newman.json)¶

{
  "collection": "collection.json",
  "environment": "environment.json",
  "globals": "globals.json",
  "iterationCount": 5,
  "delayRequest": 1000,
  "timeoutRequest": 10000,
  "reporters": ["cli", "html", "json"],
  "reporter": {
    "html": {
      "export": "./reports/report.html",
      "template": "./custom-template.hbs"
    },
    "json": {
      "export": "./reports/report.json"
    }
  },
  "bail": false,
  "insecure": false,
  "color": "on"
}

Data File for Iterations (CSV)¶

username,password,expected_status
user1,pass123,200
user2,pass456,200
admin,admin789,200
invalid,wrong,401

Data File for Iterations (JSON)¶

[
  {
    "username": "user1",
    "password": "pass123",
    "expected_status": 200
  },
  {
    "username": "user2",
    "password": "pass456",
    "expected_status": 200
  }
]

Reporter Options¶

# HTML Reporter with all options
newman run collection.json \
  -r html \
  --reporter-html-export ./reports/report.html \
  --reporter-html-template ./template.hbs \
  --reporter-html-title "API Test Report"

# JSON Reporter
newman run collection.json \
  -r json \
  --reporter-json-export ./reports/output.json

# JUnit Reporter
newman run collection.json \
  -r junit \
  --reporter-junit-export ./reports/junit.xml

# CLI Reporter (suppress specific outputs)
newman run collection.json \
  -r cli \
  --reporter-cli-no-summary \
  --reporter-cli-no-failures

Common Use Cases¶

Use Case 1: CI/CD Pipeline Integration¶

#!/bin/bash
# Jenkins/GitLab CI script for API testing

# Run collection with environment
newman run api-tests.json \
  -e production.json \
  -r cli,junit \
  --reporter-junit-export ./test-results/junit.xml \
  --bail \
  --suppress-exit-code

# Check exit code
if [ $? -eq 0 ]; then
  echo "All tests passed"
  exit 0
else
  echo "Tests failed"
  exit 1
fi

Use Case 2: Data-Driven Testing¶

# Test multiple user scenarios from CSV
newman run user-registration.json \
  -d user-data.csv \
  -e staging.json \
  -r html,cli \
  --reporter-html-export ./reports/registration-tests.html \
  --delay-request 500 \
  --timeout-request 15000

Use Case 3: Multi-Environment Testing¶

#!/bin/bash
# Test across multiple environments

ENVIRONMENTS=("dev" "staging" "production")

for env in "${ENVIRONMENTS[@]}"; do
  echo "Testing $env environment..."
  newman run collection.json \
    -e "environments/${env}.json" \
    -r html \
    --reporter-html-export "./reports/${env}-report.html" \
    --bail

  if [ $? -ne 0 ]; then
    echo "Tests failed in $env environment"
    exit 1
  fi
done

echo "All environments tested successfully"

Use Case 4: Scheduled API Monitoring¶

#!/bin/bash
# Cron job for API health monitoring (run every 15 minutes)
# */15 * * * * /path/to/api-monitor.sh

DATE=$(date +%Y%m%d-%H%M%S)

newman run health-check.json \
  -e production.json \
  -r json,html \
  --reporter-json-export "./logs/health-${DATE}.json" \
  --reporter-html-export "./logs/health-${DATE}.html" \
  --timeout-request 5000 \
  --suppress-exit-code

# Send alert if tests fail
if [ $? -ne 0 ]; then
  echo "API health check failed at ${DATE}" | mail -s "API Alert" admin@example.com
fi

Use Case 5: Programmatic Execution (Node.js)¶

// test-runner.js
const newman = require('newman');

newman.run({
    collection: require('./collection.json'),
    environment: require('./environment.json'),
    reporters: ['cli', 'html', 'json'],
    reporter: {
        html: {
            export: './reports/report.html'
        },
        json: {
            export: './reports/report.json'
        }
    },
    iterationCount: 3,
    delayRequest: 500,
    timeout: 10000
}, function (err, summary) {
    if (err) { 
        console.error('Collection run failed:', err);
        process.exit(1);
    }

    console.log('Collection run complete!');
    console.log('Total requests:', summary.run.stats.requests.total);
    console.log('Failed requests:', summary.run.stats.requests.failed);
    console.log('Test failures:', summary.run.stats.tests.failed);

    // Exit with error code if tests failed
    if (summary.run.stats.tests.failed > 0) {
        process.exit(1);
    }
});

Best Practices¶

Use Environment Variables: Store sensitive data (API keys, passwords) in environment files, never hardcode in collections
Implement Proper Timeouts: Set realistic --timeout-request values based on your API's expected response times to avoid false failures
Enable Detailed Reporting: Use multiple reporters (-r cli,html,junit) for comprehensive test results and CI/CD integration
Version Control Your Collections: Export collections from Postman and store in Git alongside your codebase for version tracking
Use Data Files for Scalability: Leverage CSV/JSON data files with -d flag for testing multiple scenarios without duplicating requests
Implement Retry Logic: For flaky tests, wrap newman commands in retry loops or use CI/CD retry mechanisms
Organize Collections by Purpose: Separate smoke tests, regression tests, and integration tests into different collections for targeted execution
Export and Archive Results: Always use --export-environment and --export-globals to capture runtime state for debugging
Secure SSL Certificates: Use --ssl-client-cert and --ssl-client-key for authenticated API testing, avoid --insecure in production
Monitor Performance: Track execution times in reports to identify slow endpoints and potential performance degradation

Troubleshooting¶

Issue	Solution
"newman: command not found"	Ensure Node.js is installed and newman is in PATH: `npm install -g newman` or use full path `/usr/local/bin/newman`
SSL certificate verification failures	Use `--insecure` flag for self-signed certificates or add CA bundle with `--ssl-extra-ca-certs ca-bundle.pem`
Request timeouts in CI/CD	Increase timeout with `--timeout-request 30000` (30 seconds) or check network connectivity in CI environment
Environment variables not loading	Verify JSON structure matches Postman format, ensure `"enabled": true` for all variables, check file path is correct
Collection runs but no output	Specify reporter explicitly: `-r cli` or check if output is redirected. Use `--verbose` for detailed logging
"Cannot find module" errors	Install newman locally in project: `npm install newman` or verify global installation: `npm list -g newman`
Tests pass in Postman but fail in newman	Check for timing issues, add `--delay-request 1000`, verify environment variables are properly exported
Memory issues with large collections	Run collections in smaller batches using `--folder` flag or increase Node.js memory: `NODE_OPTIONS=--max-old-space-size=4096 newman run`
Docker volume mount issues	Use absolute paths: `docker run -v /absolute/path:/etc/newman -t postman/newman run collection.json`
Exit code always 0 despite failures	Remove `--suppress-exit-code` flag or check CI/CD script isn't ignoring exit codes with `\|\| true`
Reporter files not generated	Ensure output directory exists, check write permissions, use absolute paths for `--reporter-*-export` options
Data file iterations not working	Verify CSV/JSON format matches expected structure, ensure `-d` flag points to correct file, check for encoding issues

Additional Resources¶

Exporting Collections from Postman¶

# Using Postman API to export collection
curl -X GET \
  'https://api.getpostman.com/collections/<collection-uid>' \
  -H 'X-Api-Key: <your-postman-api-key>' \
  -o collection.json

# Run exported collection
newman run collection.json

Installing Newman Reporters¶

# HTML reporter (included by default)
npm install -g newman-reporter-html

# HTMLExtra reporter (enhanced HTML reports)
npm install -g newman-reporter-htmlextra

# Confluence reporter
npm install -g newman-reporter-confluence

# Slack reporter
npm install -g newman-reporter-slack

# TeamCity reporter
npm install -g newman-reporter-teamcity

Using Custom Reporters¶

# Run with custom reporter
newman run collection.json -r htmlextra

# HTMLExtra with options
newman run collection.json \
  -r htmlextra \
  --reporter-htmlextra-export ./report.html \
  --reporter-htmlextra-darkTheme \
  --reporter-htmlextra-title "Custom API Tests"

Parallel Execution Pattern¶

# Using GNU Parallel for concurrent execution
parallel -j 4 newman run ::: \
  auth-tests.json \
  user-tests.json \
  order-tests.json \
  payment-tests.json

# Using background jobs
newman run collection1.json -e env1.json & \
newman run collection2.json -e env2.json & \
newman run collection3.json -e env3.json & \
wait

echo "All collections completed"