Postman CollectionsPostman CLI

Postman CLI commands and options

View as Markdown

Availability of some Postman CLI commands depend on your Postman plan.

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

Basic command options

postman

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

Options

OptionDetails
--help, -hReturns information about Postman CLI commands and options.
--version, -vReturns the version number for the Postman CLI.
Tip

You can run the man postman command to return a manual page with the Postman CLI commands and 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.

Any local operations work without a login requirement. Commands that interact with the Postman cloud require you to be signed in.

If you’re using the Postman CLI from a network with outbound restrictions, you must allowlist specific domains to connect to Postman.

postman login

The login command prompts you to securely sign in and authenticate from the browser.

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

OptionDetails
--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, environments, and specifications to Postman workspaces in the cloud. Add the commands to your CI/CD script to automate these tasks during the deployment process. Learn more about adding workspace commands to your CI/CD pipeline.

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

OptionDetails
--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/resources.yaml file in your working directory.

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, environment, and specification 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.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--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-prepareSkip the prepare step before pushing.
-y, --yesSkip all confirmation prompts.

Workflow

  1. Validate - Checks if the collections, environments, and specifications 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/resources.yaml file in your working directory.

If the resources.yaml file contains collection, environment, or specification 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 HTTP requests using the postman collection run command. With a paid plan, you can also run collections with gRPC and GraphQL requests.

postman collection run

This command runs a collection and displays run results in the terminal. If you’re signed in to Postman, the command sends the run results to the Postman cloud. Learn how to sign in to Postman with the postman login command.

Specify the collection with its file path if you’re running it locally. If you’re signed in to Postman, specify the collection with its ID to send the results to the Postman cloud.

You can find the collection ID in Postman. Click the Items icon Items tab, click Collections in the sidebar, and select a collection. Then click the Info icon Info tab in the right sidebar to view or copy the collection ID.

Options

OptionDetails
--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-unicodeReplaces all symbols in the output with their plain text equivalents.
--environment [UID] or [file-path], -eSpecifies 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], -gSpecifies 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](This option is only supported in Postman v11 and earlier.) 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.
--iteration-count [number], -nSpecifies the number of times the collection will run when used in conjunction with the iteration data file.
--iteration-data [file-path], -dSpecifies 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-redirectsPrevents the Postman CLI from automatically following 3XX redirect responses.
--insecure, -kTurns off SSL verification checks and enables self-signed SSL certificates.
--mock [file-path]Specifies the path to a mock server configuration file in JSON format. This starts a mock server using the specified configuration, runs the collection against the mock server, and then stops the mock server. Make sure you also have a JavaScript file with an HTTP server that sets the request and example response for simulating real API behavior. You can use this option in your CI/CD script to run a collection against a mock server during your deployment process. Learn how to create a mock server in your Git repository.
--no-insecure-file-readPrevents reading of files situated outside of the working directory.
--silentTurns 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, -xSpecifies 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.
--verboseShows 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. Only the cli report output is supported for collections with HTTP, gRPC, and GraphQL requests. To learn more, go to Generate collection run reports using the Postman CLI.

Examples

$postman collection run postman/collections/myCollectionName
$
$postman collection run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Migrate collections

You can migrate collections from the v2.1 JSON format to the v3 YAML format with the postman collection migrate command.

postman collection migrate

Use this command to migrate your existing v2.1 collection to the new v3 collection format.

Options

OptionDetails
-o, --output <directory>Specifies the directory to migrate your new collection to. If you don’t specify a directory, the Postman CLI saves the new collection in the current directory.

Examples

$postman collection migrate your-existing-collection.json
$postman collection migrate your-existing-collection.json --output path/to/your-new-collection

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.

In Postman, you can also convert an API request into a Postman CLI code snippet. Copy the generated code snippet, add options to help you test your request, then send the request with the Postman CLI.

Options

OptionDetails
--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], -dSpecifies request body content. Supports inline string or @filepath syntax for files. For example: --body '{"name": "John"}' or --body @data.json
--debugShows detailed information in debug mode, including retry attempts, redirects, and timing breakdowns.
--environment [UUID] or [file-path], -eSpecifies an environment file path or UUID. Resolves variables in the URL, headers, and body.
--form [field], -fSpecifies 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], -HSpecifies a header in key-value format. Can be used multiple times. For example: -H Content-Type:application/json
--output [path], -oSaves the complete response to a JSON file, including status, headers, body, and more. Use for debugging or further processing.
--response-onlySuppresses all output except the response body. This is useful for piping to other commands.
--redirects-follow-methodPreserves the original HTTP method when 3xx redirect responses. Redirects are followed with the GET method by default.
--redirects-ignorePrevents 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-referrerRemoves 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.
--verboseShows 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.

To use this command, sign in to Postman with the postman login command.

You can find the monitor ID in Postman. Click the Services icon Services tab, click Monitors in the sidebar, and select a monitor. Then click the Info icon Monitor details tab in the right sidebar to view or copy the monitor ID.

Options

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

Example

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

postman runner start

Private API Monitoring is available on Postman Enterprise plans.

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.

You can’t use the --proxy and --egress-proxy options together.

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.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--id <runner-id>Specifies the runner ID.
--key <runner-key>Specifies the runner key that authenticates your runner with the Postman cloud.
--egress-proxyRuns 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.
--metricsRuns 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

Run flows

You can use the postman flows commands to run, manage, and analyze flows.

postman flows list

The postman flows list command lists the flows available in a workspace. Specify the workspace by its ID.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
-w, --workspace [workspace ID]Specifies the workspace by its ID. This option is required for the postman flows list command.

Example

postman flows list --workspace ab12a1bb-1a12-1234-123a-123ab1234a1a

postman flows trigger

You can use the postman flows trigger command to trigger a deployed flow to run. The deployed flow must have a request trigger. This command requires the flow’s ID as an argument. You can also assign values to the flow’s inputs with the --input option.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--input [key=value/path.json]Set flow inputs with key=value pairs and/or paths to JSON files.

Example

postman flows trigger 12ab12a1ab123ab1234a1234

postman flows deploy

You can use the postman flows deploy command to deploy a flow to the Postman cloud. This command requires the flow’s ID as an argument and the --path option. The --path option is the URL segment for the trigger, and must be unique for the team. For example, in the URL deployed-flow.flows.pstmn.io/api/default/new-flow, the path is /new-flow.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--path [path]Specifies the path that will be added to the domain where the flow is deployed. This option is required for the postman flows deploy command.

Example

postman flows deploy 12ab1ab1a1234567890a1234 --path deployed-flow-path

postman flows run

This command runs a single flow from your local repo. The flow runs requests and logic blocks entirely locally on your machine, making it ideal for CI/CD workflows. Successful runs return status and output. The postman flows run command has options to set input values, show run log information, and use values from a scenario. This command requires the local flow’s file path as an argument.

The postman flows run command is available with Postman Enterprise plans.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
-x, --suppress-exit-codeSpecify whether or not to override the default exit code for the current run.
--verboseShow detailed information about the flow run and each request (method, URL, assertions).
--input [key=value/path.json]Set flow inputs with key=value pairs and/or paths to JSON files.
--input-file [path.json]Set flow inputs from JSON files.
--scenario [name]Reference a pre-built scenario as flow inputs by its name. Can be combined with --input to override values.

Examples

$postman flows run postman/flows/[flow-filename].json
$
$postman flows run postman/flows/[flow-filename].json --input [input name]=[value]
$
$postman flows run postman/flows/[flow-filename].json --input path/to/[input-filename].json
$
$postman flows run postman/flows/[flow-filename].json --scenario "[scenario name]"
$
$postman flows run postman/flows/[flow-filename].json --scenario "[scenario name]" --input [input name]=[value]

postman flows update

You can use the postman flows update command to update auth and online/offline settings for a deployed flow. This command requires the flow’s ID as an argument.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--trigger [on/off]Sets the deployed flow’s status to online (on) or offline (off).
--auth [on/off]Turns the flow’s authentication setting on or off.

Example

$postman flows update 12ab1ab1a1234567890a1234 --trigger on --auth off

postman flows list-runs

You can use the postman flows list-runs command to fetch run history for a deployed flow in a specified workspace. The result displays the run’s timestamp, ID, duration, status, and flow name in a table. This command requires the --workspace option.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
-w, --workspace [workspace ID]Specifies the workspace by its ID. This option is required for the postman flows list-runs command.
--flow [flow ID]Filter by flow ID.
--range [time range]Specifies the time window in minutes (1m), hours (1h), or days (1d). Default is 1 hour (1h).

Example

postman flows list-runs --workspace ab12a1bb-1a12-1234-123a-123ab1234a1a --range 1d

postman flows get-run

You can use the postman flows get-run command to analyze a specific run.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--run-id [run ID]Specifies the run by its ID. This option is required for the postman flows get-run command.
--logsShows the full event log including each block’s ID, input, and output.
--filter [block ID]Narrows output by block ID.

Example

$postman flows get-run main/1a123ab1

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.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--data-file [path]Specifies the path to a data file with custom values to use for each virtual user. The file must be in CSV or JSON format. Learn more about using a data file to simulate virtual users.
--duration [minutes], -dThe duration of the performance test in minutes. Default is 10.
--environment [ID], -eSpecifies an environment by its ID. Variables in the collection are resolved from the environment.
--globals [ID], -gSpecifies globals by its ID. Variables in the collection are resolved from globals.
--load-profile [profile], -p

The load profile type to use for the performance test. Accepts fixed, ramp-up, spike, or peak. The default is ramp-up.

  • With fixed, the number of virtual users is constant during the performance test.
  • With ramp-up, the number of virtual users gradually increases from 25% to 100%, and then maintains at 100%.
  • With spike, the number of virtual users starts at 10%, spikes to 100%, then drops back down to 10%.
  • With peak, the number of virtual users gradually increases from 20% to 100%, maintains at 100%, then gradually decreases back down to 20%.
--pass-if [condition]

Specifies a condition that determines whether the performance test passes or fails. The condition must be in the function(metric, value) format.

Functions:

  • less_than(metric, value) - The test passes if the metric is less than the value.
  • less_than_eq(metric, value) - The test passes if the metric is less than or equal to the value.
  • greater_than(metric, value) - The test passes if the metric is greater than the value.
  • greater_than_eq(metric, value) - The test passes if the metric is greater than or equal to the value.

Metrics:

  • avg - The response time of all requests averaged together, in milliseconds.
  • p90 - The 90th percentile of response times, in milliseconds.
  • p95 - The 95th percentile of response times, in milliseconds.
  • p99 - The 99th percentile of response times, in milliseconds.
  • error_rate - The percentage of requests with an error. Errors indicate runtime issues such as timeouts, connection or TLS failures, or uncaught exceptions in user scripts.
  • rps - The number of requests sent per second.

Examples:

  • --pass-if "less_than(p95, 500)" - The test passes if the 95th percentile of response times is less than 500 milliseconds.
  • --pass-if "less_than_eq(error_rate, 5)" - The test passes if the percentage of requests with an error is less than or equal to 5%.
--vu-count [number]The number of peak virtual users that simulate traffic to your API. The default is 20.

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)"

Run mock servers

You can use the postman mock run command to start a mock server from a configuration file.

To run a collection against a mock server, use the --mock option with the postman collection run command.

postman mock run

This command starts a mock server from a configuration file in JSON format. With the configuration file, you can configure details like the mock server’s port number, name, script, and more. The mock server runs on the specified port until you stop it. Make sure you also have a JavaScript file with an HTTP server that sets the request and example response for simulating real API behavior.

Add the command to your CI/CD script to start a mock server as a dependency for your application or test suite. Once running, your service or external tests can send requests to it as if it were a real API. This enables you to simulate API behavior for testing and development.

Learn how to create a mock server in your Git repository.

Example

$postman mock run mock-config.json

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.

To use this command, sign in to Postman with the postman login command.

You can find the specification ID in Postman. Click Items icon Items tab, click Specs in the sidebar, and select a specification. Then click the Info icon Specification Info tab in the right sidebar to view or copy the specification ID.

Options

OptionDetails
--fail-severity [severity], -fTriggers 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], -oControls 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):

Example output

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:

1file,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

The postman api lint command is only supported for API Builder objects in Postman v11. The Postman API Builder isn’t supported in Postman v12 and later. Learn about using the API Builder in Postman v11 and earlier.

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.

This command supports APIs in the Postman API Builder that aren’t linked to Git.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--fail-severity [severity], -fTriggers 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, -xSpecifies 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

The postman publish api command is only supported for API Builder objects in Postman v11. The Postman API Builder isn’t supported in Postman v12 and later. Learn about using the API Builder in Postman v11 and earlier.

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.

To use this command, sign in to Postman with the postman login command.

Options

OptionDetails
--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-pollSpecifies not to poll for completion status of the publish action.
--suppress-exit-code, -xSpecifies 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.

  • 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>

If you specify a file when a folder is required, or a folder when a file is required, the api publish command returns the following error: API Definition <file/folder> isn't part of API <apiId>. Try the command again using the other option.