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

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

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

Configuration

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

1
{
2
  "schemaVersion": "1",
3
  "workspace": {
4
    "id": "your-workspace-id"
5
  },
6
  "entities": {
7
    "collections": ["./collections/collection-name.postman_collection.json"],
8
    "environments": ["./environments/environment-name.postman_environment.json"]
9
  }
10
}

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

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:

1
{
2
  "schemaVersion": "1",
3
  "workspace": {
4
    "id": "your-workspace-id"
5
  },
6
  "entities": {
7
    "collections": ["./collections/collection-name.postman_collection.json"],
8
    "environments": ["./environments/environment-name.postman_environment.json"]
9
  }
10
}

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

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

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

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

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

Run performance tests

You can use the postman performance run command to configure and run performance tests for collections within your CI/CD pipeline.

postman performance run

This command runs a performance test for a specified collection in the Postman cloud. Add the command into your CI/CD script to run a performance test during your deployment process. Then your team can use your Postman tests to catch performance issues. Learn more at Run a performance test using the Postman CLI.

The command runs the performance test against the specified collection, returning the performance test results in Postman. Specify the collection with its ID.

Options

Examples

postman performance run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12
postman performance run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 \
  --vu-count 100 \
  --duration 30
postman performance run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 \
  --vu-count 100 \
  --duration 20 \
  --load-profile spike \
  --pass-if "less_than(p95, 800)"

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

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:

1
{
2
  "violations": [
3
    {
4
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
5
      "line number": "13",
6
      "path": "paths./spacecrafts/{spacecraftIds}.parameters.0",
7
      "severity": "WARNING",
8
      "issue": "Parameter \"spacecraftId\" must be used in path \"/spacecrafts/{spacecraftIds}\".",
9
      "issue type": "Syntax"
10
    },
11
    {
12
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
13
      "line number": "19",
14
      "path": "paths./spacecrafts/{spacecraftIds}.get",
15
      "severity": "WARNING",
16
      "issue": "Operation must define parameter \"{spacecraftIds}\" as expected by path \"/spacecrafts/{spacecraftIds}\".",
17
      "issue type": "Syntax"
18
    },
19
    {
20
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
21
      "line number": "4",
22
      "path": "info",
23
      "severity": "WARNING",
24
      "issue": "The info object should have a description.",
25
      "issue type": "Governance"
26
    },
27
    {
28
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
29
      "line number": "21",
30
      "path": "paths./spacecrafts/{spacecraftIds}.get.responses",
31
      "severity": "WARNING",
32
      "issue": "Operation should return a 5xx HTTP status code",
33
      "issue type": "Governance"
34
    }
35
  ]
36
}

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

1
file,line number,path,severity,issue,issue type
2
../../../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
3
../../../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
4
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,4,info,WARNING,The info object should have a description.,Governance
5
../../../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

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

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>