> ## Documentation Index
> Fetch the complete documentation index at: https://www.openpmm.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate the CLI

> Authorize the OpenPMM CLI in a browser and select a Workspace.

Run the browser authorization flow. You do not need to create or copy an API
key.

```bash theme={null}
openpmm auth login
```

The CLI opens OpenPMM in your browser. Sign in, choose a Workspace when your
account has more than one, and select **Authorize CLI**. The CLI creates a
full-access API key, stores it in a user-only file, and completes the command.
It never receives your browser cookie or password.

For an agent-friendly flow, return authorization metadata immediately, then
resume after browser approval:

```bash theme={null}
openpmm auth login --no-wait --json
openpmm auth login --resume --json
```

The JSON metadata includes `sensitive: true` because the one-time browser URL
authorizes this CLI. Treat the complete JSON result as a credential. The CLI
stores the device secret locally, and neither JSON response contains the device
secret or resulting API key.

When a JSON command has no credential, the error has a `null` HTTP status and
includes these commands in its structured `recovery` object. The error is
local. OpenPMM did not receive an HTTP request.

## Use an environment variable

Use the environment for automation and one-time `npx` commands:

```bash theme={null}
export OPENPMM_API_KEY=opm_live_...
openpmm accounts show --json
```

The environment has priority over a stored credential.

## Import an existing API key

Send the key through stdin. The CLI does not accept an API key as a flag,
positional argument, or URL.

```bash theme={null}
printf '%s' "$OPENPMM_API_KEY" | openpmm auth login --with-token
unset OPENPMM_API_KEY
openpmm accounts show
```

Use `--with-token` only when you already have an API key. The normal browser
authorization is faster and keeps the key out of your clipboard.

The CLI stores credentials in `~/.config/openpmm/credentials.json`. On systems
with POSIX permissions, the directory is mode `0700` and the file is mode
`0600`. `openpmm auth logout` removes the local credential for the active API
origin. It does not revoke the key in OpenPMM.

<Warning>
  The credential store is an internal CLI implementation detail. Agents and
  scripts must not read, parse, copy, export, or reuse its API key. Use the
  `openpmm` command for a CLI-managed workflow.
</Warning>

If you build a direct `/v1` API integration, create a separate API credential
with the minimum required scopes. Keep it in your secret manager. Do not import
the CLI credential into an existing HTTP client.

Create, rotate, and revoke API keys in the OpenPMM portal. These operations
require a recent browser session.

<Warning>
  Treat an API key like a password. Do not put it in source control, command arguments, URLs, screenshots, or logs.
</Warning>

## Select a workspace

The browser flow stores the approved Workspace. If a key can access exactly
one Workspace, the CLI also discovers it automatically.

```bash theme={null}
openpmm workspaces list --json
openpmm posts list
```

Pass a Workspace only when the key can access more than one:

```bash theme={null}
export OPENPMM_WORKSPACE=ws_01JABCDEF
openpmm destinations list --json
```

`--workspace` has priority over `OPENPMM_WORKSPACE` and the Workspace stored by
browser authorization. The CLI never guesses when more than one Workspace is
available.

## Select an API origin

The production API is the default. Use `--api-base-url` or
`OPENPMM_API_BASE_URL` for an approved staging or self-hosted deployment.

```bash theme={null}
openpmm workspaces list \
  --api-base-url https://api.openpmm.com/v1 \
  --json
```

The CLI validates the origin and `/v1` path. It refuses private `/api/...`
routes and URLs that contain credentials.