Skip to navigation

Postman CLI request commands (postman request)

View as Markdown

This topic covers request testing commands for the Postman CLI.

postman request

Use the postman request 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 place of the target URL, you can also pass the path to a local request file.

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.

The command reports its events to the API Catalog and Application Inventory by default. To turn this off, pass --report-events=false.

Usage

postman request [method] <url | request-file> [options]
[method]
Defaults to GET

The HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, or OPTIONS).

<url | request-file>

The target URL for the request, or the path to a local HTTP request file (*.request.yaml or *.request.yml). A request file is the file a collection uses to store a single request on disk, as defined by the Postman Collections schema. If the path matches an existing file, the command loads it as a request. Otherwise, it treats the value as a URL. You can put a method before either one.

A request file runs only the request it holds, and the request is sent to the URL saved in that file. You can’t override the saved URL separately.

The request also inherits authentication, variables, and scripts from the collection and folders the file sits in. The command resolves files that the saved request body references relative to the request file.

The options you pass override the saved values:

  • Headers override saved headers with the same name, ignoring case. Other saved headers remain.
  • Body and form options replace the saved body.
  • Authentication options override matching credentials and keep other credentials of the same authentication type.
  • Script options replace the request’s own script. Scripts from its collection and folders still run.
  • Redirect and TLS options override the saved settings.
  • The --environment option selects the environment.

The command resolves body and script file paths that you pass as options from the current working directory.

Options

--auth-[type]-[parameter] [value]

Specifies the authentication type and parameters. Supports the basic, bearer, digest, oauth1, oauth2, hawk, aws, ntlm, and apikey authentication types.

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. Pass the content inline, @filepath to read a UTF-8 file, or - to read from standard input. The command sends the content of a file or standard input as a raw body and keeps its whitespace. To upload a file as multipart form data, use --form instead. A JSON body uses the application/json content type unless you set one with --header.

For example: --body '{"name": "John"}', --body @data.json, or --body -

--cookie-jar [path]

Specifies the file path for a JSON cookie jar to load cookies from before the request runs. This uses the tough-cookie library to deserialize the file.

--dataset [path-or-dir]

Loads one or more local .dataset.yaml files, or directories of them, for the request to use. Pass --dataset more than once to load multiple datasets.

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

--export-cookie-jar [path]

Specifies the path where the Postman CLI outputs the final cookie jar file after the request completes. This uses the tough-cookie library to serialize the file.

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

--insecure, -k

Turns off SSL verification checks and enables self-signed SSL certificates.

--output [path], -o

Saves the complete response to a JSON file, including status, headers, body, and more. Use for debugging or further processing.

--report-events

Events are reported to the API Catalog and Application Inventory by default, whether you pass --report-events. To turn reporting off, pass --report-events=false. You can also use --no-report-events.

--response-only

Suppresses all output except the response body. This is useful for piping to other commands.

--quiet

A hidden alias for --response-only. Suppresses all output except the response body. You can’t use it with --verbose or --debug.

--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]
Defaults to 0

Specifies the number of retry attempts for failed requests, like a 400 Bad Request code. Useful for unreliable endpoints or rate limited APIs.

--retry-delay [number]
Defaults to 1000

Specifies the time (in milliseconds) to wait to retry the request.

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

--ssl-client-cert <path>

Specifies the path to a client certificate (PEM).

--ssl-client-cert-list <path>

Specifies the path to a client certificates configuration (JSON).

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

--timeout [number]
Defaults to 300000

Specifies the time (in milliseconds) to wait for the request to complete.

--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 POST https://api.example.com/users --body @payload.json
postman request PUT https://api.example.com/users/123 --body - < payload.json
postman request ./postman/collections/Orders/CreateOrder.request.yaml --environment ./dev.environment.yaml
postman request https://api.example.com/data \
--auth-apikey-key "apikey" \
--auth-apikey-value "abc123xyz" \
--auth-apikey-in query

Exit codes

The postman request command sets a process exit code so scripts and CI/CD pipelines can act on the result:

  • 0 — the response status code is 2xx or 3xx and all tests passed.
  • 1 — the response status code isn’t 2xx or 3xx, and no tests failed.
  • 2 — the command can’t read the body file, or standard input is attached to an interactive terminal when you pass --body -. The command doesn’t send the request.
  • N — the number of failed tests, when one or more tests fail (for example, 3 when three tests fail). This takes precedence over 1. If the response status also isn’t 2xx or 3xx, you get the test count, not 1.

postman request grpc

Use the postman request grpc command to invoke a gRPC method, or to list and describe the methods a server exposes. The service definition comes from server reflection unless you pass --proto or --protoset. The command requires you to be signed in to Postman.

postman request grpc is available on Postman paid plans. For more information, see the pricing page.

Credential metadata, such as authorization, x-api-key, and cookie, appears as [REDACTED] in the output.

Usage

postman request grpc <url | request-file> [method] [options]
<url | request-file>
Required

The server address, or the path to a local gRPC request file (*.request.yaml or *.request.yml). A scheme of http:// or grpc:// selects plaintext, and https:// or grpcs:// selects TLS. For an address without a scheme, the command detects TLS with server reflection. This detection needs reflection: with --proto or --protoset, a bare address defaults to plaintext, so use a grpcs:// address or --tls for a TLS server. The value can contain {{variables}}.

[method]

The method to invoke, as package.Service/Method (package.Service.Method also works). Overrides the method saved in a request file. With --list-methods, limits the list to one service.

Options

--list-methods

Lists the services and methods instead of invoking one, with each method’s streaming kind and message types.

--describe

Describes the method instead of invoking it, including its message types and a request message template to fill in.

--proto <path>

Reads the service definition from a .proto file or URL instead of using server reflection. Can be used multiple times.

--import-path <dir>

The directory to resolve --proto imports from. Can be used multiple times.

--protoset <path>

Reads the service definition from a compiled FileDescriptorSet. Can be used multiple times.

--tls

Connects with TLS to an address without a scheme, the same as grpcs://.

--server-name <name>

The name to verify the server’s TLS certificate against, when it differs from the address.

--emit-defaults

Includes fields that hold their default value in response messages.

--script-before-invoke <script>

A script to run before the call is invoked, as inline JavaScript or @path. pm.request holds the message and metadata.

--script-on-message <script>

A script to run on every response message as it arrives, as inline JavaScript or @path. pm.message holds the message.

--script-after-response <script>

A script to run once the call ends, as inline JavaScript or @path. pm.response holds the status, metadata, and messages, and the command reports pm.test() results.

The command also accepts these postman request options: --header, --body, --environment, --timeout, --insecure, --ssl-client-cert, --ssl-client-key, --ssl-client-passphrase, --ssl-client-cert-list, --ssl-extra-ca-certs, --output, --verbose, and --response-only. It rejects HTTP-only options with exit code 2.

Send authorization as metadata with one of these options, using one authentication type for each request:

  • --auth-apikey-key and --auth-apikey-value
  • --auth-basic-username and --auth-basic-password
  • --auth-bearer-token
  • --auth-oauth2-access-token and --auth-oauth2-header-prefix

Examples

postman request grpc localhost:50051 --list-methods
postman request grpc localhost:50051 helloworld.Greeter/SayHello --describe
postman request grpc localhost:50051 helloworld.Greeter/SayHello --body '{"name": "Ada"}'

Exit codes

  • 0 — The call ended with status OK and every test passed, or the command listed or described the methods.
  • 1 — The call or the schema load failed, the call ended with a non-OK status, or a test failed.
  • 2 — Usage error, including a method the schema doesn’t define.
  • 3 — You’re not signed in to Postman.
  • 8 — Your plan doesn’t include gRPC requests.