PaleBlueDot CLI

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:

1. Starts local HTTP server listening for callback (port 8080-8090 auto-select)
2. Opens browser to https://www.palebluedot.ai/login?redirect_uri=http://localhost:{port}/callback
3. Waits for browser callback (5 minute timeout)
4. After successful callback, calls API to exchange for session
5. 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:

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

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

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:

1. Session cookie format is correct (includes session=xxx)
2. User ID is correct (pure number)
3. 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

Security Note: Configuration file uses 0600 permissions to ensure only the current user can read sensitive information.