PaleBlueDot CLI

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:

FieldDescriptionIDToken IDNAMEToken nameQUOTARemaining quotaUSEDUsed quotaMODELSAvailable model restrictionsSTATUSStatus (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

ParameterDescription--nameToken name (required)--quotaRemaining quota (default: unlimited)--expiresExpiration timestamp--modelsModel 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

ParameterDescription--limitItems per page (default: 20)--pagePage number (default: 1)--modelFilter by model--tokenFilter 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

FieldDescriptionbase_urlAPI base URLcookieSession cookie for authenticationuser_idUser IDapi_keyAPI Key (optional)

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