Postman CLI command options

This topic covers the commands and options supported by the Postman CLI.

Basic command line options

postman

The base command of the Postman CLI is postman. Run this command with the syntax and options detailed below.

Options

Option	Details
--help, -h	Returns information about Postman CLI commands and options.
--version, -v	Returns the version number for the Postman CLI.

Example

postman -v

Sign in and out

You can use the Postman CLI to sign in and out of Postman with the login and logout commands.

postman login

The login command prompts you to securely sign in and authenticate from the browser. Signing in is required once per session.

If you purchased a Postman EU Data Residency plan, the login command also requires the --region option. Use this option with the argument eu to specify that your instance of Postman is hosted in the EU region.

You can also use the --with-api-key option to authenticate using your Postman API key. This method is recommended when using the Postman CLI from your CI/CD pipeline, but you can also use this method from your local machine.

You remain signed in until you use the logout command or your Postman credentials or API key expire.

Options

Option	Details
--with-api-key <api-key>	Authenticate the user with the given API key.
--region <region>	Specify that your instance of Postman is hosted in the EU region. Accepts eu.

Examples

postman login

postman login --with-api-key ABCD-1234-1234-1234-1234-1234

postman login --with-api-key ABCD-1234-1234-1234-1234-1234 --region eu

postman logout

This command signs you out of Postman and deletes the stored API key.

Example

postman logout

Sync local elements with workspaces

The Postman CLI includes workspace commands to validate, synchronize, and push local collections and environments to Postman workspaces in the cloud.

postman workspace prepare

This command validates and prepares local collections and environments for pushing to a Postman workspace. It checks for valid UUIDs, regenerates IDs if needed, and ensures all items and responses have proper IDs.

Options

Option	Details
--collections-dir <path>	Path to the collections directory. The default is postman/collections.
--environments-dir <path>	Path to the environments directory. The default is postman/environments.

Configuration

The command expects a .postman/config.json file in your working directory with the following structure:

{
  "schemaVersion": "1",
  "workspace": {
    "id": "your-workspace-id"
  },
  "entities": {
    "collections": ["./collections/collection-name.postman_collection.json"],
    "environments": ["./environments/environment-name.postman_environment.json"]
  }
}

Collection and environment paths can be relative (resolved from .postman/) or absolute. Only valid JSON files are processed. Invalid paths like empty strings and non-JSON files are automatically filtered with warnings.

Example

postman workspace prepare

postman workspace push

This command pushes local collection and environment changes to your Postman workspace. It synchronizes your local files with the workspace in the Postman cloud, performing create, update, and delete operations as needed.

Options

Option	Details
--collections-dir <path>	Path to the collections directory. The default is postman/collections.
--environments-dir <path>	Path to the environments directory. The default is postman/environments.
--no-prepare	Skip the prepare step before pushing.
-y, --yes	Skip all confirmation prompts.

Workflow

1. Validate - Checks if the collections and environments exist globally and in the target workspace.
2. Prepare (unless --no-prepare) - Runs prepare automatically if invalid or missing IDs are detected.
3. Sync - Creates, updates, or deletes entities to match your local state.
4. Update Local Files - After successful creation, updates local files with server-returned IDs.

Configuration

The command expects a .postman/config.json file in your working directory with the following structure:

{
  "schemaVersion": "1",
  "workspace": {
    "id": "your-workspace-id"
  },
  "entities": {
    "collections": ["./collections/collection-name.postman_collection.json"],
    "environments": ["./environments/environment-name.postman_environment.json"]
  }
}

If the config.json file contains collection or environment paths, those specific files are used instead of directory scanning.

Example push with automatic prepare and interactive prompts

postman workspace push

Example push without the prepare step

postman workspace push --no-prepare

Example automatic push without prompts (useful for CI/CD)

postman workspace push --yes

Run collections

You can run your collections with the postman collection run command:

postman collection run

This command runs a collection and sends the run results to the Postman cloud. You can specify the collection with its file path or Collection ID.

Options

Option	Details
--bail [optional modifiers]	Specifies whether to stop a collection run on encountering the first error. --bail can optionally accept two modifiers: --folder and --failure. --folder skips the entire collection run if there are any errors. If a test fails, --failure stops the collection run after completing the current script.
--color [value]	Controls colors in the CLI output. Accepts on, off, and auto. The default is auto. With auto, the Postman CLI attempts to automatically turn color on or off based on the color support in the terminal. This behavior can be changed by using the on or off value.
--cookie-jar [path]	Specifies the file path for a JSON cookie jar. This uses the tough-cookie library to deserialize the file.
--delay-request [number]	Specifies a delay (in milliseconds) between requests. The default is 0.
--disable-unicode	Replaces all symbols in the output with their plain text equivalents.
--environment [UID] or [file-path], -e	Specifies an environment file path or UID.
--env-var "[environment-variable-name]=[environment-variable-value]"	Specifies environment variables in a key=value format. Multiple CLI environment variables can be added by using --env-var multiple times, for example: --env-var "this=that" --env-var "alpha=beta".
--export-cookie-jar [path]	Specifies the path where the Postman CLI will output the final cookie jar file after completing a run. This uses the tough-cookie library to serialize the file.
--global-var "[global-variable-name]=[global-variable-value]"	Specifies global variables in a key=value format. Multiple CLI global variables can be added by using --global-var multiple times, for example: --global-var "this=that" --global-var "alpha=beta".
--globals [file-path], -g	Specifies a path to a file containing global variables. Global variables are similar to environment variables but have lower precedence and can be overridden by environment variables having the same name.
--integration-id [ID]	Specifies an integration ID when using an integration with CI/CD. This sends the Postman CLI results to the correct integration in Postman. When you generate the Postman CLI command for a Git integrated API collection, the integration ID is automatically added to the command. To learn how to generate the Postman CLI command with the integration ID, go to Configure the Postman CLI for CI.
--iteration-count [number], -n	Specifies the number of times the collection will run when used in conjunction with the iteration data file.
--iteration-data [file-path], -d	Specifies the local file path to a data file (JSON or CSV) to use for each iteration.
-i [requestUID] or [folderUID]	Runs only the specified folder UID or request UID from the collection. Multiple items can be run in order by specifying -i multiple times, for example: postman collection run collectionUID -i folder1UID -i folder2UID.
-i [requestName] or [folderName]	Runs only the specified folder name or request name from the collection. If there are duplicate names, the Postman CLI runs the folder or request that appears first.
--ignore-redirects	Prevents the Postman CLI from automatically following 3XX redirect responses.
--insecure, -k	Turns off SSL verification checks and enables self-signed SSL certificates.
--no-insecure-file-read	Prevents reading of files situated outside of the working directory.
--silent	Turns off terminal output.
--ssl-client-cert-list <path>	Specifies the path to a client certificates configuration (JSON).
--ssl-client-cert <path>	Specifies the path to a client certificate (PEM).
--ssl-client-key <path>	Specifies the path to a client certificate private key.
--ssl-client-passphrase <passphrase>	Specifies the client certificate passphrase (for a protected key).
--ssl-extra-ca-certs <path>	Specifies more trusted CA certificates (PEM).
--suppress-exit-code, -x	Specifies whether to override the default exit code for the current run.
--timeout [number]	Specifies the time (in milliseconds) to wait for the entire collection run to complete.
--timeout-request [number]	Specifies a time (in milliseconds) to wait for requests to return a response. The default is 0.
--timeout-script [number]	Specifies the time (in milliseconds) to wait for scripts to complete. The default is 0.
--verbose	Shows detailed information for the collection run and each request sent.
--working-dir [path]	Sets the path of the working directory to use while reading files with relative paths. This defaults to the current directory.
--reporters [reporter], -r [reporter]	Generates a local report for the collection run in the specified format: cli, json, junit, and html. If the --reporters option isn’t specified, the cli report is output by default. To learn more, go to Generate collection run reports using the Postman CLI.

Examples

postman collection run /myCollectionFolderName/myCollectionFile.json

postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Run requests

You can test and debug HTTP requests from the command line with the postman request command.

postman request

Use this command to test and debug HTTP requests from the command line with the Postman CLI. Use many of Postman’s features for sending requests, including authentication, environment variables, test assertions, and more. The command accepts the request’s method (GET, POST, PUT, DELETE, PATCH, HEAD, or OPTIONS) as the first argument, defaulting to GET if a method isn’t provided. The command accepts the target URL as the second argument.

Options

Option	Details
--auth-[type]-[parameter] [value]	Specifies the authentication type and parameters. Supports the following authentication types: basic, bearer, digest, oauth1, oauth2, hawk, aws, ntlm, and apikey. For example: --auth-basic-username user --auth-basic-password pass or --auth-apikey-key "X-API-Key" --auth-apikey-value "abc123" --auth-apikey-in header
--body [body], -d	Specifies request body content. Supports inline string or @filepath syntax for files. For example: --body '{"name": "John"}' or --body @data.json
--debug	Shows detailed information in debug mode, including retry attempts, redirects, and timing breakdowns.
--environment [UUID] or [file-path], -e	Specifies an environment file path or UUID. Resolves variables in the URL, headers, and body.
--form [field], -f	Specifies multipart/form-data in key=value format. Use @filepath syntax for files. Can be used multiple times. For example: -f "name=John" or -f "avatar=@photo.jpg"
--header [header], -H	Specifies a header in key-value format. Can be used multiple times. For example: -H Content-Type:application/json
--output [path], -o	Saves the complete response to a JSON file, including status, headers, body, and more. Use for debugging or further processing.
--response-only	Suppresses all output except the response body. This is useful for piping to other commands.
--redirects-follow-method	Preserves the original HTTP method when 3xx redirect responses. Redirects are followed with the GET method by default.
--redirects-ignore	Prevents the Postman CLI from automatically following 3xx redirect responses. Redirects are followed by default.
--redirects-max [number]	Specifies the maximum number of 3xx redirect responses to follow. There is no limit by default. Useful for preventing redirect loops.
--redirects-remove-referrer	Removes the Referer header when following 3xx redirect responses. The Referer header is sent with redirects by default.
--retry [number]	Specifies the number of retry attempts for failed requests, like a 400 Bad Request code. Useful for unreliable endpoints or rate limited APIs. The default is 0.
--retry-delay [number]	Specifies the time (in milliseconds) to wait to retry the request. The default is 1000.
--script-post-request [script]	Adds JavaScript that runs after the request runs. Supports inline JavaScript or @filepath syntax for files. Learn more about writing post-response scripts. For example: --script-post-request "console.log(pm.response.json());"
--script-pre-request [script]	Adds JavaScript that runs before the request runs. Supports inline JavaScript or @filepath syntax for files. Learn more about writing pre-request scripts. For example: --script-pre-request "pm.environment.set('timestamp', Date.now());"
--timeout [number]	Specifies the time (in milliseconds) to wait for the request to complete. The default is 300000.
--verbose	Shows detailed information for the request and response, including headers, body, and metadata.

Examples

postman request GET https://api.example.com/users

postman request POST https://api.example.com/users \
    --body '{"name": "John", "email": "john@example.com"}'

postman request https://api.example.com/data \
    --auth-apikey-key "apikey" \
    --auth-apikey-value "abc123xyz" \
    --auth-apikey-in query

Run monitors

You can use the postman monitor run command to trigger monitor runs within your CI/CD pipeline. You can also use the postman runner start command to run your organization’s APIs from your internal network.

postman monitor run

This command runs a monitor in the Postman cloud. Add the command into your CI/CD script to trigger a monitor run during your deployment process. Then your team can use your Postman tests to catch regressions and configuration issues. Learn more at Run a monitor using the Postman CLI.

The command also invokes the monitor and polls Postman for the run’s completion, returning the monitor results. Specify the monitor with its monitor ID.

Options

Option	Details
--timeout <number>	Specifies the time (in milliseconds) to wait for the entire run to complete.
--suppress-exit-code, -x	Specifies whether to override the default exit code for the current run.

Example

postman monitor run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

postman runner start

With Private API Monitoring, you can use runners to monitor and test your organization’s APIs from your internal network, without publicly exposing your endpoints.

Run this command to start a runner from your internal network that regularly polls Postman for upcoming monitor runs. The collection’s tests run in your internal network. Then the test results are sent back to the Postman cloud, making them available in the monitor results. Provide the runner ID and key from the command you copied when you created the runner. Learn more about setting up a runner in your internal network.

Optionally, you can configure the runner to route HTTP and HTTPS traffic through a proxy server that enforces outbound request policies. You can use the --proxy option to provide the URL for the proxy server used by your organization. Or you can use the --egress-proxy option to enable the built-in proxy and use the --egress-proxy-authz-url option to provide the URL for the runner authorization service that evaluates outbound request policies. Learn more about configuring a runner to use a proxy server.

If the runner is running in the background, stop the runner using your system’s process control. You can also press Control+C or Ctrl+C to stop the runner.

Options

Option	Details
--id <runner-id>	Specifies the runner ID.
--key <runner-key>	Specifies the runner key that authenticates your runner with the Postman cloud.
--egress-proxy	Runs the runner with the built-in proxy enabled. This option requires --egress-proxy-authz-url.
--egress-proxy-authz-url <url>	Specifies a custom runner authorization service URL. Instead of specifying this option, you can define the URL using the POSTMAN_RUNNER_AUTHZ_URL environment variable. This is required with --egress-proxy.
--metrics	Runs a metrics server available at the /health/live endpoint. Useful for health checks in orchestration environments, like Kubernetes.
--metrics-port <port>	Specifies a port number where the metrics server can expose health checks and metrics. Default is 9090.
--proxy <url>	Specifies your organization’s proxy URL. Instead of specifying this option, you can define the URL using the HTTP_PROXY and HTTPS_PROXY environment variables.
--ssl-extra-ca-certs <path>	Specifies the path to the file with one or more trusted CA certificates in PEM format. Used for custom SSL certificate validation.

Examples

postman runner start --id 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --key 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

postman runner start --id 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --key 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --proxy http://example.com:8080

postman runner start --id 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --key 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --egress-proxy --egress-proxy-authz-url http://authz.example.com

postman runner start --id 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --key 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 --metrics --metrics-port 12044 --ssl-extra-ca-certs /path/to/certs.pem

Governance and security

API governance is the practice of applying a defined set of standards consistently across the API design and testing phases of your development process. The Postman CLI includes commands that checks your API specifications in Spec Hub and the Postman API Builder against your team’s configured Postman API governance and security rules.

postman spec lint

This command runs syntax validation and governance rule checks against a single- or multi-file API specification in Spec Hub. Provide the local file path or ID for a specification that’s in OpenAPI 2.0, 3.0, or 3.1 format. If you’re providing the local file path for a multi-file specification, provide the path to the root file.

By default, if you provide a local file path for a specification, the command runs syntax validation and governance checks using the All workspaces governance group. Use the --workspace-id option to run governance checks using the rules from a specific workspace.

Options

Option	Details
--fail-severity [severity], -f	Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARNING, and ERROR (default).
--output [output format], -o	Controls the output format for issues found in the OpenAPI specification. Accepts JSON or CSV. Defaults to table view if no output format is specified. See examples of JSON and CSV output.
--workspace-id [workspace-id]	Run syntax validation and governance rule checks using the rules from a particular workspace by providing its ID. You can use this option if you provide the local file path for a specification. Learn how to get a workspace’s ID.

Example

postman spec lint openapi.yaml --workspace-id 987654321-54321ef-4321-1ab2-1ab2-ab1234112a12
postman spec lint 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Example output

You can change the output of governance rule violations to JSON or CSV. If you don’t specify an output, it defaults to table view.

The following is an example of the output in table format (default):

The following is an example of the output in JSON format:

{
  "violations": [
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "13",
      "path": "paths./spacecrafts/{spacecraftIds}.parameters.0",
      "severity": "WARNING",
      "issue": "Parameter \"spacecraftId\" must be used in path \"/spacecrafts/{spacecraftIds}\".",
      "issue type": "Syntax"
    },
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "19",
      "path": "paths./spacecrafts/{spacecraftIds}.get",
      "severity": "WARNING",
      "issue": "Operation must define parameter \"{spacecraftIds}\" as expected by path \"/spacecrafts/{spacecraftIds}\".",
      "issue type": "Syntax"
    },
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "4",
      "path": "info",
      "severity": "WARNING",
      "issue": "The info object should have a description.",
      "issue type": "Governance"
    },
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "21",
      "path": "paths./spacecrafts/{spacecraftIds}.get.responses",
      "severity": "WARNING",
      "issue": "Operation should return a 5xx HTTP status code",
      "issue type": "Governance"
    }
  ]
}

The following is an example of the output in CSV format:

file,line number,path,severity,issue,issue type
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,13,paths./spacecrafts/{spacecraftIds}.parameters.0,WARNING,"Parameter ""spacecraftId"" must be used in path ""/spacecrafts/{spacecraftIds}"".",Syntax
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,19,paths./spacecrafts/{spacecraftIds}.get,WARNING,"Operation must define parameter ""{spacecraftIds}"" as expected by path ""/spacecrafts/{spacecraftIds}"".",Syntax
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,4,info,WARNING,The info object should have a description.,Governance
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,21,paths./spacecrafts/{spacecraftIds}.get.responses,WARNING,Operation should return a 5xx HTTP status code,Governance

postman api lint

This command runs validation checks for governance and security rules against the API specification provided in the Postman config file, a local file, or a UUID. The api lint command shows a warning if it’s unable to find the API ID to send data back to Postman.

Options

Option	Details
--fail-severity [severity], -f	Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARN, and ERROR (default).
--suppress-exit-code, -x	Specifies whether to override the default exit code for the current run.

Example

postman api lint my-definition-file.json
postman api lint 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Publish an API version

You can publish API versions in the Postman API Builder from the command line with the Postman CLI. Use the Postman CLI to automate the API version publishing process.

postman publish api

Publish a snapshot of an API for the given apiId. All elements linked to the API are published by default. You can choose which elements to publish by using other command options.

When publishing an API that’s linked with Git, you must enter the command from inside the local Git repo. Also, you must provide paths to the schema directory and collection paths instead of IDs.

Options

Option	Details
--name <name>	Specifies the name of the version to publish.
--release-notes <releaseNotes>	Enter release notes as a string in quotes for the version to publish. This option supports Markdown.
--collections <collectionIds/paths...>	Specifies the collections to publish. If the API is linked with Git, provide the filePath instead of the ID.
--api-definition <apiDefinitionId/directory/file>	Specifies the API specification to publish. If the API is linked with Git, provide the schemaDirectoryPath or schemaRootFilePath instead of the ID.
--do-not-poll	Specifies not to poll for completion status of the publish action.
--suppress-exit-code, -x	Specifies whether to override the default exit code for the current run.

Example for repos not linked with Git

postman api publish <apiId> --name v1\
--release-notes "# Some release notes information"\
--collections <collectionId1> <collectionId2>\
--api-definition <apiDefinitionId>

Examples for repos linked with Git

The options for the api publish command differ depending on if you specified a schema folder or schema root file when setting up the Git integration. Git integrations added in Postman v10.18 or later use a schema root file. Git integrations added in other Postman versions use a schema folder. Learn more about connecting an API in the Postman API Builder to a Git repository.

• If the API uses a schema folder, publish the API using the --api-definition <schemaDirectoryPath> option:

  postman api publish <apiId> --name v1\
  --release-notes "# Some release notes information"\
  --collections <collectionPath1> <collectionPath2>\
  --api-definition <schemaDirectoryPath>
  

• If the API uses a schema root file, publish the API using the --api-definition <schemaRootFilePath> option:

  postman api publish <apiId> --name v1\
  --release-notes "# Some release notes information"\
  --collections <collectionPath1> <collectionPath2>\
  --api-definition <schemaRootFilePath>