PaleBlueDot CLI

Command-line tool for PaleBlueDot AI platform supporting login, API token management, usage and balance queries, and browsing available AI models.

Authentication

login (Browser Mode)

Default method, automatically opens browser for OAuth login.

bash

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:

text

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.

bash

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.

bash

pbd-cli logout

---

Token Management

token list

List all tokens.

bash

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.

bash

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.

bash

pbd-cli token delete <id>

token get-key

Get the plaintext key for a token.

bash

pbd-cli token get-key <id>
pbd-cli token get-key <id> -f  # Formatted output

---

Usage Queries

usage balance

Query balance and subscription status.

bash

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.

bash

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.

bash

pbd-cli wallet        # Raw JSON output

Output:

• Balance: Account balance
• Gift Balance: Gift balance

---

Model Browsing

models list

List available AI models.

bash

pbd-cli models list        # Raw JSON output

---

Common Error Handling

session expired

text

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:

text

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:

bash

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:

yaml

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.