Skip to main content
pdd auth manages your PDD Cloud authentication state. It provides subcommands for signing in via GitHub SSO, checking the current session, retrieving the active token, clearing the token cache, and signing out.

​
Usage

pdd auth SUBCOMMAND [OPTIONS]

​
Subcommands

​
auth login

Authenticate with PDD Cloud via GitHub. Opens a web browser to complete the OAuth flow using an ephemeral code. 
pdd auth login [OPTIONS]
​
--browser / --no-browser
boolean
Control whether the browser is opened automatically. Auto-detected based on environment if not specified. Use --no-browser in headless environments — the command will display a URL to open manually.
The authentication flow:
1

Open browser

PDD opens your default browser to the GitHub login page (or prints a URL if --no-browser is set).
2

Authorize

Log in with your GitHub account and authorize PDD Cloud to access your GitHub profile.
3

Return to terminal

Once authorized, return to your terminal. PDD stores the token securely at ~/.pdd/jwt_cache.
pdd auth login

# Headless environments (no browser available)
pdd auth login --no-browser

​
auth status

Display the current authentication state and the active account. 
pdd auth status [OPTIONS]
​
--verify
boolean
default:"false"
Verify authentication by actually attempting to refresh the token. Without this flag, only cached credentials are checked.
Exit codes:
  • 0 — Authenticated
  • 1 — Not authenticated
# Quick check (uses cached credentials)
pdd auth status

# Deep verification (attempts token refresh)
pdd auth status --verify
If only a refresh token exists (no cached JWT), auth status shows a warning that the token is expired and will refresh on next use. Run pdd auth status --verify to test if the refresh will succeed, or run pdd auth login to refresh immediately.

​
auth logout

Remove the stored authentication credentials locally. Does not invalidate the token server-side. 
pdd auth logout

​
auth token

Print the current authentication token to stdout. Useful for scripts or tools that need to make authenticated requests to PDD Cloud. 
pdd auth token [OPTIONS]
​
--format
string
default:"raw"
Output format. Options:
  • raw — Print just the token string.
  • json — Print structured JSON including the token and its expiration timestamp.
# Print raw token
pdd auth token

# Print token with expiration info
pdd auth token --format json

​
auth clear-cache

Clear the stored JWT token cache. Useful when switching between environments (production vs. staging) or resolving token audience mismatch errors. 
pdd auth clear-cache
After clearing the cache, re-authenticate with pdd auth login.

​
Token storage

Authentication tokens are stored at ~/.pdd/jwt_cache. The token is automatically refreshed as needed during cloud operations.

​
Examples

# Full authentication flow
pdd auth login
pdd auth status
pdd auth token

# Verify and recover from an expired token
pdd auth status --verify
# If verification fails:
pdd auth logout && pdd auth login
  • pdd connect — Requires authentication to register a session with PDD Cloud.
  • pdd sessions — Manage remote sessions that become available after authenticating.

Build docs developers (and LLMs) love

Get started for freeTalk to us