Newman command reference

Use Newman’s command line options to customize your collection runs. You can use options to set up a collection run, configure request delays and timeouts, specify SSL details, and more. When you run a collection iteratively, you can specify different data sets and variables for each iteration. After a run finishes, Newman exits with a status code that you can pass to your continuous integration (CI) tool.

To use options, add them to the newman run command after you specify the collection file or URL:

$ newman run my-collection.json [options]

To view a list of available options for Newman, run the following command:

$ newman run -h

Basic options

-h, --help

Output usage information.

-v, --version

Output the version number.

Setup options

-e, --environment [file\|URL]

Specify the file path or URL of environment variables.

-g, --globals [file\|URL]

Specify the file path or URL of global variables.

-d, --iteration-data [file]

Specify the local file path to a data file (JSON or CSV) to use for each iteration. To learn more, see Data file example.

-n, --iteration-count [number]

Specify the number of times for the collection to run. Use with the iteration data file.

--folder [folderName]

Specify a folder to run requests from. You can specify more than one folder by using this option multiple times, specifying one folder for each time the option is used.

--working-dir [path]

Set the path of the working directory to use while reading files with relative paths. Defaults to the current directory.

--no-insecure-file-read

Prevents reading of files located outside of the working directory.

--export-environment [path]

The path to the file where Newman will output the final environment variables file before completing a run.

--export-globals [path]

The path to the file where Newman will output the final global variables file before completing a run.

--export-collection [path]

The path to the file where Newman will output the final collection file before completing a run.

--postman-api-key [api-key]

The Postman API key used to load resources using the Postman API.

Request options

--delay-request [number]

Specify a delay (in milliseconds) between requests.

--timeout [number]

Specify the time (in milliseconds) to wait for the entire collection run to complete.

--timeout-request [number]

Specify the time (in milliseconds) to wait for requests to return a response.

--timeout-script [number]

Specify the time (in milliseconds) to wait for scripts to complete.

SSL options

--ssl-client-cert [path]

The path to the public client certificate file. Use this option to make authenticated requests.

--ssl-client-key [path]

Optionally, you can add the path to the private client key that verifies certificate ownership.

--ssl-client-passphrase [passphrase]

Optionally, you can add a secret passphrase to protect the private client key.

--ssl-client-cert-list [path]

The path to the configuration JSON file containing the SSL client certificate list. Use this option to set several SSL client certificates according to a URL or hostname. To learn more, see an example client certificate list.

This option has a higher priority over the --ssl-client-cert, --ssl-client-key, and --ssl-client-passphrase options. If there is no URL match in the SSL client certificate list, these options are used instead.

--ssl-extra-ca-certs [path]

The path to the file that has one or more trusted CA certificates in PEM format. You can use this option when you don’t want to use the --insecure option.

Output options

--color [value]

Specify the color of the CLI output: on, off, or auto (default).

--verbose

Show detailed information of the collection run and each request sent.

--silent

Prevent Newman from showing CLI output.

-x, --suppress-exit-code

Specify whether to override the default exit code for the current run. Continue running tests even after a failure, but exit with code=0. To learn more, see Exit status.

--disable-unicode

Turn off Unicode text encoding. When supplied, all symbols in the output will be replaced by their plain text equivalents.

-r [reporter-name], --reporters [reporter-name]

Generate a report about the current collection run. Specify one or more reporter names: cli (default when using Newman as a CLI), json, junit, progress, and emojitrain. Specify more than one reporter name as a comma-separated list, for example, -r cli,json. Learn more about using reporters with Newman.

More configuration options

--bail [optionalModifiers]

Stops the collection run when a test script fails.

Optionally, you can add modifiers to this option: folder and failure. You can add folder to skip the entire collection run if an invalid folder was specified using the --folder option, or an error was encountered in general. You can add failure to stop an entire collection run (after completing the current test script) when a test fails.

-k, --insecure

Turn off SSL verification checks, and allow self-signed SSL certificates.

--ignore-redirects

Turn off automatic following of 3XX redirect responses.

--cookie-jar [path]

Specify the file path for a JSON Cookie Jar. Uses tough-cookie to deserialize the file.

--export-cookie-jar [path]

The path to the file where Newman will output the final cookie jar file before completing a run. Uses tough-cookie to serialize the file.

--global-var "[global-variable-name]=[global-variable-value]"

Specifies global variables on the command line, in a key=value format. Multiple global variables can be added by using --global-var multiple times, for example, --global-var "color=blue" --global-var "pet=cat".

--env-var "[environment-variable-name]=[environment-variable-value]"

Specifies environment variables in a key=value format on the command line. You can add multiple environment variables using --env-var multiple times, for example: --env-var "color=blue" --env-var "pet=cat".

Exit status

By default, Newman exits with a status code of 0 if everything runs as expected without any exceptions. You can configure your continuous integration (CI) tool to pass or fail a build based on Newman’s exit codes. To override the default exit code for the current run, use -x or --suppress-exit-code option.

Use the --bail option to make Newman stop a run if it encounters a test case error with a status code of 1. This status code can then be used by your CI tool or build system. For example:

$ newman run my-collection.json -e dev-environment.json --bail

Data file example

To use a different set of data or variables for each iteration in a collection run, use the -d option to specify a JSON or CSV file.

The following example shows a JSON data file for a run with two iterations, with each iteration using different values for a set of variables.

1 [
2     {
3         "url": "http://127.0.0.1:5000",
4         "user_id": "1",
5         "id": "1",
6         "token_id": "123123"
7     },
8     {
9         "url": "http://postman-echo.com",
10         "user_id": "2",
11         "id": "2",
12         "token_id": "899899"
13     }
14 ]

To run the collection, use the -d option and specify the data file. For example:

$ newman run my-collection.json -d data-file.json

The following example shows the same data formatted in a CSV file.

$ url, user_id, id, token_id
$ http://127.0.0.1:5000, 1, 1, 123123123
$ http://postman-echo.com, 2, 2, 899899

To learn more about formatting data files for collection runs, see Run collections using imported data.