*** title: Postman CLI command options updated: 2024-12-04T00:00:00.000Z topictype: reference slug: docs/postman-cli/postman-cli-options max-toc-depth: 2 ---------------- This topic covers the commands and options supported by the [Postman CLI](/docs/postman-cli/postman-cli-overview/). ## 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. | You can run the `man postman` command to return a manual page with the Postman CLI commands and options. #### Example ```plaintext postman -v ``` ## Sign in and out You can use the Postman CLI to sign in and out of Postman with the [`login`](#postman-login) and [`logout`](#postman-logout) commands. If you're using the Postman CLI from a network with outbound restrictions, you must [allowlist specific domains](/docs/getting-started/installation/installation-and-updates/#use-postman-behind-a-firewall) to connect to Postman. ### `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](/docs/administration/enterprise/about-eu-data-residency/), 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](/docs/developer/postman-api/authentication/#generate-a-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. {/*TODO: behavior if you log in a second time, how you create an alias, etc. */} #### Options | Option | Details | | :------------------------- | :------------------------------------------------------------------------------ | | `--with-api-key ` | Authenticate the user with the given API key. | | `--region ` | Specify that your instance of Postman is hosted in the EU region. Accepts `eu`. | #### Examples ```plaintext 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. {/*TODO: alias behavior */} #### Example ```plaintext 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. The `postman workspace` commands are a beta feature available on Basic and Professional plans. Enterprise plan users can request access from their Postman Customer Success Manager. ### `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 to the collections directory. The default is `postman/collections`. | | `--environments-dir ` | 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: ```json { "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 ```plaintext 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 to the collections directory. The default is `postman/collections`. | | `--environments-dir ` | 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: ```json { "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 ```plaintext postman workspace push ``` #### Example push without the prepare step ```plaintext postman workspace push --no-prepare ``` #### Example automatic push without prompts (useful for CI/CD) ```plaintext postman workspace push --yes ``` ## Run collections The Postman CLI supports running HTTP collections. You can't run multi-protocol collections with the CLI. 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. You can find the collection ID in Postman. Click **Collections** in the sidebar and select a collection. Then click **Info** Info icon in the right sidebar to view or copy the 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](/docs/integrations/ci-integrations/#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 ` | Specifies the path to a client certificates configuration (JSON). | | `--ssl-client-cert ` | Specifies the path to a client certificate (PEM). | | `--ssl-client-key ` | Specifies the path to a client certificate private key. | | `--ssl-client-passphrase ` | Specifies the client certificate passphrase (for a protected key). | | `--ssl-extra-ca-certs ` | 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](/docs/postman-cli/postman-cli-reporters/). | #### Examples ```plaintext 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. In Postman, you can also [convert an API request into a Postman CLI code snippet](/docs/sending-requests/create-requests/generate-code-snippets/). Copy the generated code snippet, add options to help you test your request, then send the request with the Postman CLI. #### 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](/docs/tests-and-scripts/write-scripts/test-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](/docs/tests-and-scripts/write-scripts/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 ```plaintext 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](/docs/postman-cli/postman-cli-run-monitor/). 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. You can find the monitor ID in Postman. Click **Monitors** in the sidebar and select a collection. Then click Info icon **Info** in the right sidebar to view or copy the monitor ID. #### Options | Option | Details | | ---------------------------- | ---------------------------------------------------------------------------- | | `--timeout ` | 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 ```plaintext postman monitor run 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12 ``` ### `postman runner start` Private API Monitoring is a beta feature available with [Postman Basic, Professional, and Enterprise plans](https://www.postman.com/pricing/). To enable Private API Monitoring and the `postman runner start` command in your Enterprise team, contact your Postman Customer Success Manager. With [Private API Monitoring](/docs/monitoring-your-api/runners/overview/), 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](/docs/monitoring-your-api/runners/set-up-a-runner-in-your-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](/docs/monitoring-your-api/runners/proxy-server/overview/). 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. #### Options | Option | Details | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--id ` | Specifies the runner ID. | | `--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 ` | 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 ` | Specifies a port number where the metrics server can expose health checks and metrics. Default is `9090`. | | `--proxy ` | 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 ` | Specifies the path to the file with one or more trusted CA certificates in PEM format. Used for custom SSL certificate validation. | #### Examples ```plaintext 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. The `postman performance run` command is a beta feature. ### `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](/docs/postman-cli/postman-cli-run-performance-test/). The command runs the performance test against the specified collection, returning the performance test results in Postman. Specify the collection with its ID. #### Options | Option | Details | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--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](/docs/collections/performance-testing/performance-test-data-files/). | | `--duration [minutes]`, `-d` | The duration of the performance test in minutes. Default is 10. | | `--environment [ID]`, `-e` | Specifies an environment by its ID. Variables in the collection are resolved from the environment. | | `--globals [ID]`, `-g` | Specifies 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 ```plaintext 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 and security rules are available with [Postman Enterprise plans](https://www.postman.com/pricing/). 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](#postman-spec-lint) and the [Postman API Builder](#postman-api-lint) against your team's configured [Postman API governance and security rules](/docs/api-governance/api-governance-overview/). ### `postman spec lint` This command runs syntax validation and governance rule checks against a single- or multi-file API specification in [Spec Hub](/docs/design-apis/specifications/overview/). 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](/docs/design-apis/specifications/add-files-to-a-specification/#about-multi-file-specifications). 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. Click Info icon **Specification Info** in the [right sidebar](/docs/getting-started/basics/navigating-postman/#right-sidebar) of a specification and copy its ID. #### 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](#example-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](/docs/collaborating-in-postman/using-workspaces/internal-workspaces/use-workspaces/#get-the-workspace-id). | #### Example ```plaintext 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](https://assets.postman.com/postman-docs/v11/postman-cli-spec-lint-table-v11-74-2.png) The following is an example of the output in JSON format: ```json { "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: ```csv 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. This command supports APIs in the [Postman API Builder](/docs/design-apis/api-builder/overview/) that aren't linked to Git. #### 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 ```plaintext 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](/docs/design-apis/api-builder/versioning-an-api/api-versions/) 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 ` | Specifies the name of the version to publish. | | `--release-notes ` | Enter release notes as a string in quotes for the version to publish. This option supports Markdown. | | `--collections ` | Specifies the collections to publish. If the API is linked with Git, provide the `filePath` instead of the ID. | | `--api-definition ` | 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 ```plaintext postman api publish --name v1\ --release-notes "# Some release notes information"\ --collections \ --api-definition ``` #### 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](/docs/design-apis/api-builder/versioning-an-api/overview/). * If the API uses a schema folder, publish the API using the `--api-definition ` option: ```plaintext postman api publish --name v1\ --release-notes "# Some release notes information"\ --collections \ --api-definition ``` * If the API uses a schema root file, publish the API using the `--api-definition ` option: ```plaintext postman api publish --name v1\ --release-notes "# Some release notes information"\ --collections \ --api-definition ``` 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 isn't part of API `. Try the command again using the other option.