Postman CLI vs Newman: Which Command-Line Runner Should You Use?

For years, running Postman collections outside the desktop app usually meant using Newman. Postman now also provides the Postman CLI, so teams have two command-line options for running collections in CI/CD. Both can execute requests and pm.test assertions, but they fit different workflows: Newman is an open-source, account-free runner, while Postman CLI is tied to the Postman cloud and can report results back to your workspace.

Try Apidog today

If you want a runner that only needs a collection file, Newman is usually the simpler choice. If your team already manages APIs inside Postman and wants centralized run history or governance checks, Postman CLI may fit better. This guide compares both tools from an implementation perspective so you can choose the right one for your pipeline.

What Newman is

Newman is Postman’s original command-line collection runner. It is open source, distributed as an npm package, and free to use. It runs exported Postman collection files, executes every request and pm.test assertion, and returns a non-zero exit code when tests fail.

That makes Newman easy to use in CI/CD because your build can fail automatically when an API test fails.

npm install -g newman

newman run checkout-api.postman_collection.json \
  --environment staging.postman_environment.json

Newman’s main advantage is independence. It does not require:

• A Postman account
• A Postman API key
• A connection to Postman’s cloud
• A collection stored in a workspace

You provide a local JSON collection file, and Newman runs it.

Newman also supports reporters. Out of the box, you can generate CLI output and JUnit XML. Community reporters such as newman-reporter-htmlextra can generate richer HTML reports.

npm install -g newman newman-reporter-htmlextra

newman run checkout-api.postman_collection.json \
  --environment staging.postman_environment.json \
  --reporters cli,htmlextra,junit \
  --reporter-htmlextra-export reports/newman-report.html \
  --reporter-junit-export reports/newman-results.xml

Because Newman is a Node.js package, you can also run it programmatically from scripts.

For more background, see this guide on the difference between Newman and Postman.

What Postman CLI is

Postman CLI is Postman’s newer official command-line tool. It is installed as a standalone binary rather than an npm package, and it authenticates with your Postman account using an API key.

Example installation and run flow:

# install, example for macOS/Linux
curl -o- "https://dl-cli.pstmn.io/install/osx_64.sh" | sh

# authenticate
postman login --with-api-key YOUR_API_KEY

# run a collection
postman collection run checkout-api

The key difference is that Postman CLI is designed to connect your pipeline to the Postman platform.

With Postman CLI, you can:

• Pull collections from a Postman workspace
• Run collections from CI/CD
• Push run results back to Postman
• View results in Postman workspace history and dashboards
• Run API governance and linting checks against API definitions stored in Postman

That makes Postman CLI more than a local collection runner. It acts as a pipeline agent for teams that use Postman as their API collaboration platform.

Side-by-side comparison

Aspect	Postman CLI	Newman
Source	Closed source, official Postman tool	Open source
Install method	Install script, single binary	npm package
Postman account required	Yes, API key login	No
Collection source	Postman cloud by ID, or local file	Local JSON file
Run results	Reported back to Postman	Terminal output and reporter files
API governance/linting	Built in	Not included
Reporters	Limited; results live in Postman	CLI, JUnit, plus community HTML reporters
Offline use	Limited; designed around cloud workflows	Fully offline once files are local
Maturity	Newer	Long-established community standard
Cost	Free, but tied to Postman plan limits	Free, no account required

The main decision is whether you want Postman’s cloud involved in your test execution.

Use Postman CLI when you want results and governance inside Postman. Use Newman when you want a local, file-based runner with no platform dependency.

How they fit into CI/CD

Both tools work with common CI/CD systems, including:

• GitHub Actions
• GitLab CI
• Jenkins
• CircleCI
• Azure Pipelines
• Bitbucket Pipelines

The implementation pattern is different for each tool.

Using Newman in CI/CD

With Newman, the common pattern is:

1. Export your Postman collection as JSON.
2. Export your environment file as JSON.
3. Commit both files to your repository.
4. Install Newman in the CI job.
5. Run the collection.
6. Let Newman’s exit code pass or fail the build.

Example GitHub Actions workflow:

name: API Tests

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  newman-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Newman
        run: npm install -g newman

      - name: Run API tests
        run: |
          newman run tests/checkout-api.postman_collection.json \
            --environment tests/staging.postman_environment.json

To publish JUnit results:

name: API Tests

on:
  push:
    branches:
      - main

jobs:
  newman-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Newman
        run: npm install -g newman

      - name: Run API tests with JUnit output
        run: |
          mkdir -p reports
          newman run tests/checkout-api.postman_collection.json \
            --environment tests/staging.postman_environment.json \
            --reporters cli,junit \
            --reporter-junit-export reports/newman-results.xml

      - name: Upload test report
        uses: actions/upload-artifact@v4
        with:
          name: newman-results
          path: reports/newman-results.xml

This approach keeps the test files versioned with the application code. Pull requests can update the API code and the API tests together.

For related CI/CD examples, see these guides on automating API tests in CI/CD and API test automation with GitHub Actions.

Using Postman CLI in CI/CD

With Postman CLI, the common pattern is:

1. Store your collection in Postman.
2. Create a Postman API key.
3. Add the API key as a CI/CD secret.
4. Install Postman CLI in the job.
5. Authenticate with the API key.
6. Run the collection by ID or workspace reference.
7. View results in Postman.

Example GitHub Actions workflow:

name: Postman CLI API Tests

on:
  push:
    branches:
      - main

jobs:
  postman-cli-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Install Postman CLI
        run: |
          curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

      - name: Login to Postman
        run: postman login --with-api-key "${{ secrets.POSTMAN_API_KEY }}"

      - name: Run Postman collection
        run: postman collection run "YOUR_COLLECTION_ID"

This approach keeps the source of truth in Postman rather than in your repository. That works well if your team manages API collections, environments, and reporting from Postman.

The trade-off is that your CI job now depends on:

• A valid Postman API key
• Access to the Postman workspace
• Postman’s cloud availability
• The collection version stored in Postman

Before choosing this approach, decide whether API tests should be versioned in your repository or managed in Postman.

The governance difference

API governance is the clearest functional difference between the two tools.

Postman CLI can run API linting and governance checks against API definitions stored in Postman. These checks can evaluate rules related to naming, schema quality, security, consistency, and completeness.

In a pipeline, that means an API definition can fail the build before the change is merged.

Conceptually, the workflow looks like this:

postman login --with-api-key YOUR_API_KEY

postman api lint YOUR_API_ID

Newman does not provide equivalent API governance functionality. Newman runs collections and reports execution results. That is its scope.

So the decision is not simply “Newman vs. a newer Newman.” The tools have different jobs:

• Newman is a collection runner.
• Postman CLI is a Postman platform pipeline agent that includes collection running.

If you need automated API design enforcement inside Postman, use Postman CLI. If you only need to execute collection tests, Newman is usually simpler.

Migration considerations

If your team already uses Newman successfully, there is usually no urgent reason to migrate.

Newman is still maintained, works in CI/CD, and does not require account authentication. Migrating to Postman CLI means you need to:

• Add a Postman API key to CI secrets
• Change how collections are sourced
• Decide how Postman workspace versions map to code versions
• Accept a runtime dependency on Postman’s cloud
• Adjust reporting expectations

That migration is only worth it if you specifically want Postman-hosted run results, dashboards, or governance checks.

For new projects, start with your desired source of truth:

• If tests should live in the repo, choose Newman.
• If tests should live in Postman, choose Postman CLI.
• If you want to avoid splitting design, testing, and CI execution across multiple tools, consider an alternative API platform.

Which one should you choose?

Choose Newman if you want:

• No Postman account dependency
• Tests versioned with your code
• Local collection and environment files
• Offline-friendly execution
• Flexible reporter output
• JUnit XML for CI test dashboards
• Rich HTML reports through community reporters
• A mature open-source runner

Choose Postman CLI if you want:

• Postman workspace integration
• Results synced back to Postman
• Centralized run history
• Postman dashboards
• API governance checks
• API definition linting in CI/CD
• A workflow centered on the Postman platform

For many CI/CD pipelines, Newman is the safer default because it is simple, local, and vendor-independent. Postman CLI makes sense when the Postman platform itself is part of your team’s API governance and reporting workflow.

If you are evaluating other options, see these guides on running Postman collections in CI without Newman and API testing without Postman.

A single-tool alternative: Apidog

Both Newman and Postman CLI assume that your tests are authored in Postman. Apidog takes a different approach.

With Apidog, you can design APIs, debug requests, create automated test scenarios, and run those scenarios in CI/CD from one product. The goal is to avoid the export-and-runner split where API definitions live in one place and execution logic lives somewhere else.

A typical workflow is:

1. Design or import your API.
2. Debug requests during development.
3. Add assertions visually.
4. Build test scenarios.
5. Run those scenarios locally or in CI/CD.
6. Use the same API assets across design, testing, mocking, and automation.

Apidog also includes API design, mock servers, and performance testing features, so teams can cover more of the API lifecycle without stitching together separate tools.

You can download Apidog and use its testing features for free, including the CLI runner for pipelines.

Frequently asked questions

Is Postman CLI replacing Newman?

Postman recommends Postman CLI as its official command-line tool, but Newman is still maintained and widely used. Newman remains useful when you want an account-free runner with collection files versioned in your repository.

Does Postman CLI require a Postman account?

Yes. Postman CLI authenticates with a Postman API key and is designed to connect runs back to a Postman workspace. Newman does not require a Postman account.

Can Newman run without internet access?

Yes, as long as the collection and environment files are local and the API under test is reachable from the execution environment. Newman does not need to connect to Postman’s cloud.

Which tool gives better reports?

Newman is more flexible for standalone report files. It supports CLI and JUnit output, plus community reporters such as newman-reporter-htmlextra for HTML reports.

Postman CLI reports results into the Postman platform, which is useful if your team already works there but less flexible if you need independent report artifacts.

Can Postman CLI run a local collection file?

Yes, Postman CLI can run local collection files. However, it is primarily designed around Postman cloud workflows, where collections are pulled from a workspace and results are synced back to Postman.

If you want local files to be the source of truth with no cloud dependency, Newman fits that model better.

Which is faster in CI?

For pure collection execution, the difference is usually not the main deciding factor. Newman has a smaller footprint and avoids Postman cloud authentication and result syncing. Postman CLI may add overhead because it authenticates and connects results back to the platform.

Choose based on workflow fit first, then optimize runtime if needed.

What is the simplest default choice?

If you only need to run Postman collections in CI/CD, start with Newman. It is simple, open source, and easy to version with your code.

Choose Postman CLI when you specifically need Postman platform integration, centralized run history, or API governance checks.