Authentication and tokens

Last updated

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.

If you sign in as a different account, the CLI clears the saved organization, workspace, and site. Signing in again as the same account keeps them.

ploy login --with-device

Use the OAuth device flow for SSH sessions, remote machines, or terminals where the normal browser-based authentication flow cannot work. Run:

Sign in with device flow
ploy login --with-device

The CLI prints a verification URL and confirmation code. Open the URL on any device with a browser, sign in, confirm that the account and code match the terminal, then select Authorize CLI.

Keep the command running while you approve the request. After approval, the terminal finishes automatically and saves credentials on the machine running the CLI.

The CLI does not open a browser or start a local callback server in this mode. Device login requires human approval. Use PLOY_API_TOKEN for unattended automation.

Only approve a device login you started. Check the account and code before granting access, and never approve a code sent by someone else.

If a browser challenge stops device login, contact Ploy support and include the request ID from the message. While you wait for approval, the CLI retries short server errors automatically.

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.

Workspace API tokens cannot authorize cross-workspace copy or delete operations. Use browser-backed ploy login for a workspace transfer.

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.

Each CLI credential, including the one ploy login saves and each API token, is limited to 60 requests per minute. Database commands also have their own limits. A rate-limited command exits 1. When Ploy returns a retry delay, the message includes it; wait that long before you retry.

With --json, the error object includes retryAfterSeconds when Ploy returns a retry delay.

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 organization, 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