Authentication and tokens

ploy login

ploy login opens Ploy in your browser and stores CLI credentials after sign-in. If your account uses enhanced security, complete MFA in the browser.

Sign in
ploy login

Logging in again stores the new credential first, then attempts to revoke the previous one. --dry-run is not supported.

Headless authentication

CI jobs and other headless environments cannot complete ploy login in a browser. Create an API token in workspace Settings → Developer → API tokens, then provide it through the environment:

Authenticate with an API token
export PLOY_API_TOKEN=sk_ploy_pat_...
ploy whoami

The CLI reads PLOY_API_TOKEN on every invocation and never writes it to disk. There is no --token flag. If a stored login credential is also available, PLOY_API_TOKEN takes precedence.

Workspace scope

Each API token is pinned to one workspace. The CLI can send a different workspace from --workspace or PLOY_WORKSPACE_ID, but the API rejects the request with exit code 1 and This API token is scoped to a different workspace. ploy workspace list shows only the pinned workspace.

Expiry and identity

Choose a 30-, 90-, or 365-day expiry when you create a token. The default is 90 days, and tokens do not refresh. Use ploy whoami to confirm the pinned workspace and see how many days remain. If an expired token disappears from Settings, create a replacement.

The raw token is shown once, together with a copyable export PLOY_API_TOKEN=… line. It cannot be retrieved later. Any workspace member can create and view their own tokens. Owners and admins can view and revoke every token in the workspace so access can be removed when a member leaves or a key leaks.

Credential management

ploy logout, ploy tokens, and ploy token revoke are unavailable when PLOY_API_TOKEN is set. Each exits with code 2 and:

Unavailable command message
<command> is unavailable when PLOY_API_TOKEN is set. Manage API tokens in workspace settings → Developer.

There is no local credential to delete. API tokens also cannot create replacement credentials or revoke the browser session that created them. Manage API tokens in the web app.

Failures and rate limits

An invalid or expired token fails immediately with exit code 3 and PLOY_API_TOKEN is invalid or expired. Create a new token in workspace settings → Developer. The CLI does not attempt a refresh. A token that is not workspace-scoped also exits 3 with PLOY_API_TOKEN is not workspace-scoped.

API tokens are limited to 60 requests per minute. A rate-limited command exits 1 and includes the retry delay in the message.

ploy whoami

Confirm the account attached to the current credential. The command prints the authenticated email, optional name, and user ID.

Show the current user
ploy whoami

ploy logout

Logout revokes the current server-side CLI credential and removes local credentials. Saved workspace and site selections remain in place.

Log out or preview logout
ploy logout
ploy --dry-run logout

If the current credential already fails with 401, 403, or 404, the CLI still clears it locally.

List active CLI credentials

ploy tokens lists up to 100 active CLI refresh credentials for the current user and marks the credential in use by this CLI.

List credentials
ploy tokens

Revoke a credential

ploy token revoke <target> accepts a credential ID, an exact credential name, or the special target current. If an exact name matches more than one credential, Ploy returns a conflict instead of guessing.

Revoke a CLI credential
ploy token revoke current
ploy token revoke <token-id>
ploy --dry-run token revoke <token-id>

Revoking the current credential also removes it from local config.

Authentication failures

Commands return exit code 3 when authentication is required or credentials have expired. With a browser login, run ploy login again. With PLOY_API_TOKEN, create a replacement token in workspace Settings → Developer.

Keep going