Authentication
login (Browser Mode)
Default method, automatically opens browser for OAuth login.
pbd-cli login # Browser login (default)
pbd-cli login --port 8085 # Specify callback port
pbd-cli login --base-url https://open.palebluedot.ai
Flow Description:
- Starts local HTTP server listening for callback (port 8080-8090 auto-select)
- Opens browser to
https://www.palebluedot.ai/login?redirect_uri=http://localhost:{port}/callback
- Waits for browser callback (5 minute timeout)
- After successful callback, calls API to exchange for session
- Saves configuration locally
Successful Login Output:
Opening browser for login...
If browser doesn't open, visit: https://www.palebluedot.ai/login?redirect_uri=...
Waiting for login...
Exchanging token for session...
Login successful! Logged in as user ID: 12345
login --manual (Manual Mode)
Manually enter session cookie and user ID.
pbd-cli login --manual
Prompts for input:
- Session Cookie: Session cookie from browser (format:
session=xxx)
- User ID: User ID (number)
logout
Log out and clear local session.
pbd-cli logout
Token Management
token list
List all tokens.
pbd-cli token list # Raw JSON output
Output fields:
| Field | Description |
|---|
| ID | Token ID |
| NAME | Token name |
| QUOTA | Remaining quota |
| USED | Used quota |
| MODELS | Available model restrictions |
| STATUS | Status (enabled/disabled) |
token create
Create a new token.
pbd-cli token create --name <name>
pbd-cli token create --name prod-key --quota 100000 --models gpt-4o,claude-3-5
| Parameter | Description |
|---|
--name | Token name (required) |
--quota | Remaining quota (default: unlimited) |
--expires | Expiration timestamp |
--models | Model whitelist (comma-separated) |
token delete
Delete a token.
pbd-cli token delete <id>
token get-key
Get the plaintext key for a token.
pbd-cli token get-key <id>
pbd-cli token get-key <id> -f # Formatted output
Usage Queries
usage balance
Query balance and subscription status.
pbd-cli usage balance # Raw JSON output
Output:
- Quota: Total quota
- Used: Used quota
- Remaining: Remaining quota
- Subscription: Subscription info
usage logs
Query usage logs.
pbd-cli usage logs
pbd-cli usage logs --limit 50 --model gpt-4o
pbd-cli usage logs --page 2 --token my-token
| Parameter | Description |
|---|
--limit | Items per page (default: 20) |
--page | Page number (default: 1) |
--model | Filter by model |
--token | Filter by token name |
Wallet Balance
wallet
Query wallet balance.
pbd-cli wallet # Raw JSON output
Output:
- Balance: Account balance
- Gift Balance: Gift balance
Model Browsing
models list
List available AI models.
pbd-cli models list # Raw JSON output
Common Error Handling
session expired
Error: session expired — please run 'pbd-cli login'
Solution: Run pbd-cli login again to re-authenticate.
Browser Cannot Open
If automatic browser opening fails, the CLI will print the login URL. Open it manually in your browser:
Warning: failed to open browser: ...
Please open this URL manually: https://www.palebluedot.ai/login?redirect_uri=...
Login Timeout
Default wait time is 5 minutes. If timeout occurs, run pbd-cli login again.
Authentication Failed (Manual Mode)
Ensure:
- Session cookie format is correct (includes
session=xxx)
- User ID is correct (pure number)
- Base URL is correct (if using custom deployment)
Callback Port Occupied
If default port range (8080-8090) is occupied, use --port to specify a port:
pbd-cli login --port 9000
Configuration File
Configuration file is stored at ~/.pbd-cli/config.yaml with 0600 permissions (owner read/write only).
Configuration Structure:
base_url: https://www.palebluedot.ai
cookie: session=xxx
user_id: 12345
api_key: "" # Optional
| Field | Description |
|---|
base_url | API base URL |
cookie | Session cookie for authentication |
user_id | User ID |
api_key | API Key (optional) |
Security Note: Configuration file uses 0600 permissions to ensure only the current user can read sensitive information.
