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.

Login and guest sessions

Any local-only operation — working with files already on disk, such as linting a local collection or specification — works without being signed in.

Commands that interact with the Postman cloud require credentials accepted by that command. Most accept an API key or signed-in session; some collection and monitor commands also accept a guest session:

  • Signed in: run postman login to authenticate with your Postman account from the browser, or pass --with-api-key to sign in non-interactively.
  • Guest: outside CI and --json mode, running postman init without first signing in creates a temporary guest workspace unless you pass --no-cloud. Use this session only with commands that document guest support.

A guest session can’t own a cloud workspace. Commands like postman workspace create require an account — if you started as a guest, run postman signup first to claim your guest workspace and turn it into a full account.

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