> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Postman CLI authentication and configuration > Learn how Postman CLI credentials, regions, and local project files work together, including credential precedence, guest sessions, and the local-vs-cloud mode rule. 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 ` on most commands, or `--postman-api-key ` on [`postman collection run`](/docs/postman-cli/postman-cli-collections/#postman-collection-run) and [`postman performance run`](/docs/postman-cli/postman-cli-monitoring/#postman-performance-run). 2. The `POSTMAN_API_KEY` environment variable. 3. Your signed-in [`postman login`](/docs/postman-cli/postman-cli-auth/#postman-login) session. > **Info** > > `--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`](/docs/postman-cli/postman-cli-auth/#postman-login) 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`](/docs/postman-cli/postman-cli-auth/#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`](/docs/postman-cli/postman-cli-init/#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`](/docs/postman-cli/postman-cli-workspace/#postman-workspace-create) require an account — if you started as a guest, run [`postman signup`](/docs/postman-cli/postman-cli-auth/#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](/docs/administration/enterprise/about-eu-data-residency/), sign in with: ```bash 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. > **Info** > > `--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: | Path | Purpose | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.postman/resources.yaml` | The workspace-sync manifest. Created by [`postman init`](/docs/postman-cli/postman-cli-init/#postman-init) or by connecting a workspace, and read by [`postman workspace prepare`](/docs/postman-cli/postman-cli-workspace/#postman-workspace-prepare) and [`postman workspace push`](/docs/postman-cli/postman-cli-workspace/#postman-workspace-push) to map your local files to Postman Cloud elements. | | `.postman/config.json` | SDK generator configuration only, created by [`postman sdk init`](/docs/postman-cli/postman-cli-sdk-gen/#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](#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 * Browse [commands and global options](/docs/postman-cli/postman-cli-options/). * See [Use the Postman CLI with AI agents and CI/CD](/docs/postman-cli/postman-cli-agents-and-ci/) for non-interactive setups.