Skip to main content
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.
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.
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.