Skip to navigation
Postman CLI

Postman CLI authentication and configuration

View as Markdown

The Postman CLI (postman) resolves credentials, regions, and local file layout the same way across most commands. This page explains those shared rules.

Credential precedence

Commands that read or write Postman Cloud resources resolve a Postman API key in this order:

  1. An explicit flag on the command itself: --api-key <key> on most commands, or --postman-api-key <key> on postman collection run and postman performance run.
  2. The POSTMAN_API_KEY environment variable.
  3. Your signed-in postman login session.

--postman-api-key on collection run and performance run is only supported in the US region. For EU region authentication, sign in with postman login --region eu instead.

If POSTMAN_API_KEY is set to any value, including an empty or stale one, and the command gets no explicit --api-key or --postman-api-key option, the CLI prints a notice that it’s using that key instead of your postman login session. This helps explain a 401 or 403 that otherwise looks like a broken login. The notice is skipped for machine-readable output, such as --json.

Login and temporary sessions

The Postman CLI works in one of three states:

  • Signed in to an account. Run postman login to authenticate with your Postman account from the browser, pass --with-api-key to sign in non-interactively, or create an account with postman signup.
  • Working in a temporary session. Outside CI and --json mode, running postman init without first signing in creates a temporary workspace, unless you decline the prompt. The Postman CLI then holds credentials for an anonymous identity, and those credentials are what reach that workspace. Use this session only with commands that document support for it.
  • Signed out. The Postman CLI holds no credentials, which is the state after postman logout.

The options that start and manage a temporary session use guest in their names, such as --guest and --no-migrate-guest-workspace.

Working in a temporary session isn’t the same as being signed out. A temporary session holds real credentials, so postman logout deletes those too and ends it. Your local files stay on your machine, but the temporary workspace and anything pushed to it then become unreachable.

Any local-only operation, such as linting a collection or specification already on disk, works in any state. Commands that interact with the Postman Cloud require credentials accepted by that command. Most accept an API key or signed-in session, and some collection and monitor commands also accept a temporary session. When more than one is present, a Postman API key or a postman login session takes precedence over a temporary session.

A temporary session can’t own a cloud workspace. Commands like postman workspace create require an account. You have two ways to move a temporary workspace’s work into one:

  • postman signup creates a new account and claims the temporary workspace under it.
  • postman login signs you in to an account you already have and copies your project’s files into a new workspace there, leaving the temporary workspace unclaimed.

EU region

If your organization uses Postman EU Data Residency, sign in with:

postman login --region eu

postman init doesn’t have its own --region option — it uses whatever region your existing login session or API key already resolves to.

--postman-api-key on collection run and performance run doesn’t support the EU region. Use postman login --region eu for those commands instead.

Local project layout

The Postman CLI reads and writes two kinds of files under a hidden .postman/ directory, plus a visible postman/ directory for your actual Postman elements:

PathPurpose
.postman/resources.yamlThe workspace-sync manifest. Created by postman init or by connecting a workspace, and read by postman workspace prepare and postman workspace push to map your local files to Postman Cloud elements.
.postman/config.jsonSDK generator configuration only, created by postman sdk init. Unrelated to workspace sync.
postman/collections/Local collections.
postman/environments/Local environments.
postman/specs/Local API specifications.
postman/mocks/Local mock configurations.
postman/datasets/Local datasets.

These two .postman/ files are easy to conflate because they sit in the same directory and both configure CLI behavior, but they serve unrelated purposes: resources.yaml is about which cloud workspace your files sync to, and config.json is about how postman sdk generate builds an SDK.

Local and cloud mode

Most Postman CLI commands that take a collection, environment, specification, mock, or similar element accept either:

  • A local path — reads or writes the element on disk. No authentication is required.
  • A cloud ID — reads or writes the element in the Postman Cloud. This requires a signed-in session, a temporary session, or an API key (see Credential precedence above).

For example, postman collection run ./postman/collections/my-collection runs a local collection, while postman collection run 12345-abcde fetches and runs a cloud collection by ID. This same rule applies throughout the CLI reference — check each command’s own page for which argument forms it accepts.

Next steps