Request commands | Postman Docs

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

Usage

$ postman request [method] <url> [options]

[method]

Defaults to GET

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

<url>

The target URL for the request.

Options

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

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

--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 https://api.example.com/data \
>     --auth-apikey-key "apikey" \
>     --auth-apikey-value "abc123xyz" \
>     --auth-apikey-in query