Run the browser authorization flow. You do not need to create or copy an API
key.
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:
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:
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.
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.
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.
/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.
Treat an API key like a password. Do not put it in source control, command arguments, URLs, screenshots, or logs.
Select a workspace
The browser flow stores the approved Workspace. If a key can access exactly
one Workspace, the CLI also discovers it automatically.
Pass a Workspace only when the key can access more than one:
--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.
The CLI validates the origin and /v1 path. It refuses private /api/...
routes and URLs that contain credentials. 