better-ccflare CLI Documentation

The better-ccflare CLI provides a command-line interface for managing OAuth accounts, monitoring usage statistics, and controlling the load balancer.

Installation and Setup
Global Options and Help
Command Reference
Usage Examples
Configuration
Environment Variables
Troubleshooting

Installation and Setup

Prerequisites

Bun runtime (>= 1.2.8)
Node.js compatible system

Installation

Clone the repository:

git clone https://github.com/tombii/better-ccflare.git
cd better-ccflare

Install dependencies:

bun install

Build the CLI:

bun run build

Run the CLI:

bun run cli [command]
# or if globally installed:
better-ccflare [command]

First-time Setup

Add your first OAuth account:

bun run cli --add-account myaccount --mode claude-oauth --priority 0

Start the load balancer server:

bun run cli --serve
# or just:
bun start

Global Options and Help

Getting Help

Display all available commands and options:

bun run cli --help

Or use the short form:

bun run cli -h

Help Output Format

🎯 better-ccflare - Load Balancer for Claude

Usage: better-ccflare [options]

Options:
  --serve              Start API server with dashboard
  --port <number>      Server port (default: 8080, or PORT env var)
  --logs [N]           Stream latest N lines then follow
  --stats              Show statistics (JSON output)
  --add-account <name> Add a new account
    --mode <claude-oauth|console>  Account mode (default: claude-oauth)
    --priority <number>    Account priority (0-100, default: 0)
  --list               List all accounts
  --remove <name>      Remove an account
  --force-reset-rate-limit <name> Force-clear stale rate-limit lock fields for an account
  --pause <name>       Pause an account
  --resume <name>      Resume an account
  --set-priority <name> <priority> Set account priority (0-100)
  --analyze            Analyze database performance
  --repair-db          Check and repair database integrity
  --reset-stats        Reset usage statistics
  --clear-history      Clear request history
  --help, -h           Show this help message

Default Mode:
  bun run cli             Start server (default behavior)

Command Reference

Account Management

`--add-account <name>`

Add a new OAuth account to the load balancer pool.

Syntax:

bun run cli --add-account <name> --mode <claude-oauth|console|zai|minimax|anthropic-compatible|openai-compatible> --priority <number>

Note: All flags must be provided explicitly as the CLI requires explicit parameters.

Required Options:

--mode: Account type (required)
- claude-oauth: Claude CLI OAuth account
- console: Claude API account
- zai: z.ai account (API key)
- openai-compatible: OpenAI-compatible provider (API key)
--priority: Account priority (optional, defaults to 0)
- Range: 0-100
- Lower numbers indicate higher priority in load balancing

Account Setup Process:

Execute command with all required flags
For OAuth accounts (claude-oauth/console), opens browser for authentication
Waits for OAuth callback on localhost:7856
For API key accounts (zai/openai-compatible), prompts for API key
Stores account credentials securely in the database

`--list`

Display all configured accounts with their current status.

Syntax:

bun run cli --list

Output Format:

Accounts:
  - account1 (claude-oauth mode, priority 10)
  - account2 (console mode, priority 5)

`--remove <name>`

Remove an account from the configuration.

Syntax:

bun run cli --remove <name>

Behavior:

Removes account from database immediately
Cleans up associated session data
Account removal is immediate with no confirmation prompts

`--pause <name>`

Temporarily exclude an account from the load balancer rotation.

Syntax:

bun run cli --pause <name>

Use Cases:

Account experiencing issues
Manual rate limit management
Maintenance or debugging

`--force-reset-rate-limit <name>`

Force-clear a potentially stale account rate-limit lock.

Syntax:

bun run cli --force-reset-rate-limit <name>

What it does:

Clears rate_limited_until
Clears rate_limit_reset
Clears rate_limit_status
Clears rate_limit_remaining
Attempts to trigger immediate usage polling on running local servers

`--resume <name>`

Re-enable a paused account for load balancing.

Syntax:

bun run cli --resume <name>

Account Priorities

`--set-priority <name> <priority>`

Set or update the priority of an account. Accounts with lower priority numbers are preferred in the load balancing algorithm.

Syntax:

bun run cli --set-priority <name> <priority>

Parameters:

name: Account name to update
priority: Priority value (0-100, where lower numbers indicate higher priority)

How Priorities Work:

Accounts with lower priority numbers are selected first
Default priority is 0 if not specified
Priority affects both primary account selection and fallback order
Changes take effect immediately without restarting the server

Example:

# Set account to high priority (low number)
bun run cli --set-priority production-account 10

# Set account to medium priority
bun run cli --set-priority development-account 50

# Set account to low priority (high number)
bun run cli --set-priority backup-account 90

Statistics and History

`--stats`

Display current statistics in JSON format.

Syntax:

bun run cli --stats

Output: Returns JSON-formatted statistics including account usage, request counts, and performance metrics.

`--reset-stats`

Reset request counters for all accounts.

Syntax:

bun run cli --reset-stats

Effects:

Resets request counts to 0
Preserves account configuration
Does not affect rate limit timers

`--clear-history`

Remove all request history records.

Syntax:

bun run cli --clear-history

Effects:

Deletes request log entries
Preserves account data
Reports number of records cleared

System Commands

`--analyze`

Analyze database performance and index usage.

Syntax:

bun run cli --analyze

Output:

Database performance metrics
Index usage statistics
Query optimization suggestions

`--repair-db`

Check and repair database integrity issues.

Syntax:

bun run cli --repair-db

What it does:

Runs PRAGMA integrity_check to verify database health
Detects and fixes NULL values in numeric fields
Validates foreign key constraints
Vacuums database to reclaim space and rebuild structure
Optimizes database with ANALYZE and PRAGMA optimize

When to use:

After encountering "All accounts failed" errors
When you suspect database corruption
If you see database-related error messages
As part of regular maintenance

Example output:

🔧 BETTER-CCFLARE DATABASE REPAIR
══════════════════════════════════════════════════

🔍 Checking database integrity...
✅ Database integrity check: PASSED

🔍 Checking for NULL values in account fields...
⚠️  Found NULL values in account fields:
   - request_count: 3
   - total_requests: 2
   - session_request_count: 1

🔧 Fixing NULL values...
✅ Fixed 3 account records with NULL values

✅ Database vacuumed successfully
✅ Database optimized successfully

DATABASE REPAIR SUMMARY
══════════════════════════════════════════════════
📊 Results:
   Integrity Check: ✅ PASSED
   NULL Values Fixed: 3
   Database Vacuumed: ✅ YES

✅ Database is healthy!

Exit codes:

0: Success (database healthy or repaired)
1: Critical errors require manual intervention

Default Behavior

When no command is specified, the CLI starts the server by default:

bun run cli
# Equivalent to:
bun run cli --serve

Server and Monitoring

`--serve`

Start the API server with dashboard.

Syntax:

bun run cli --serve [--port <number>]

Options:

--port: Server port (default: 8080, or PORT env var)

Access:

API endpoint: http://localhost:8080
Dashboard: http://localhost:8080/dashboard

`--logs [N]`

Stream request logs in real-time.

Syntax:

bun run cli --logs [N]

Options:

N: Number of historical lines to display before streaming (optional)

Examples:

# Stream live logs only
bun run cli --logs

# Show last 50 lines then stream
bun run cli --logs 50

Usage Examples

Basic Account Setup

# Add a Claude CLI OAuth account with high priority (low number)
bun run cli --add-account work-account --mode claude-oauth --priority 10

# Add a Console account with medium priority
bun run cli --add-account personal-account --mode console --priority 50

# Add a backup account with low priority (high number)
bun run cli --add-account backup-account --mode claude-oauth --priority 90

# List all accounts
bun run cli --list

# Update account priority
bun run cli --set-priority backup-account 20

# View statistics
bun run cli --stats

Server Operations

# Start server on default port
bun run cli --serve
# or simply:
bun start

# Start server on custom port
bun run cli --serve --port 3000

# Stream logs
bun run cli --logs

# View last 100 lines then stream
bun run cli --logs 100

Managing Rate Limits

# Pause account hitting rate limits
bun run cli --pause work-account

# Force-clear stale rate-limit lock
bun run cli --force-reset-rate-limit work-account

# Resume after cooldown
bun run cli --resume work-account

# Reset statistics for fresh start
bun run cli --reset-stats

Maintenance Operations

# Remove account
bun run cli --remove old-account

# Clear old request logs
bun run cli --clear-history

# Analyze database performance
bun run cli --analyze

# Repair database if you encounter errors
bun run cli --repair-db

Automation Examples

# Add multiple accounts with different priorities
bun run cli --add-account "primary-account" --mode max --priority 10
bun run cli --add-account "secondary-account" --mode max --priority 50
bun run cli --add-account "backup-account" --mode max --priority 90

# Monitor account status
watch -n 5 'bun run cli --list'

# Automated cleanup
bun run cli --clear-history && bun run cli --reset-stats

# Export statistics for monitoring
bun run cli --stats > stats.json

# Prioritize specific account temporarily
bun run cli --set-priority primary-account 5
# ... run important workload ...
bun run cli --set-priority primary-account 10  # Restore normal priority

Configuration

Configuration File Location

better-ccflare stores its configuration in platform-specific directories:

macOS/Linux

~/.config/better-ccflare/better-ccflare.json

Or if XDG_CONFIG_HOME is set:

$XDG_CONFIG_HOME/better-ccflare/better-ccflare.json

Windows

%LOCALAPPDATA%\better-ccflare\better-ccflare.json

Or fallback to:

%APPDATA%\better-ccflare\better-ccflare.json

Configuration Structure

{
  "lb_strategy": "session",
  "client_id": "optional-custom-client-id",
  "retry_attempts": 3,
  "retry_delay_ms": 1000,
  "retry_backoff": 2,
  "session_duration_ms": 18000000,
  "port": 8080
}

Database Location

The SQLite database follows the same directory structure:

macOS/Linux: ~/.config/better-ccflare/better-ccflare.db
Windows: %LOCALAPPDATA%\better-ccflare\better-ccflare.db

Environment Variables

Core Configuration

Variable	Description	Default
`better-ccflare_CONFIG_PATH`	Override config file location	Platform default
`better-ccflare_DB_PATH`	Override database location	Platform default
`PORT`	Server port	8080
`CLIENT_ID`	OAuth client ID	9d1c250a-e61b-44d9-88ed-5944d1962f5e

Load Balancing

Variable	Description	Default
`LB_STRATEGY`	Load balancing strategy (only 'session' is supported)	session

Retry Configuration

Variable	Description	Default
`RETRY_ATTEMPTS`	Number of retry attempts	3
`RETRY_DELAY_MS`	Initial retry delay (ms)	1000
`RETRY_BACKOFF`	Exponential backoff multiplier	2

Session Management

Variable	Description	Default
`SESSION_DURATION_MS`	OAuth session duration (ms)	18000000 (5 hours)

Logging and Debugging

Variable	Description	Default
`LOG_LEVEL`	Log verbosity (DEBUG/INFO/WARN/ERROR)	INFO
`LOG_FORMAT`	Output format (pretty/json)	pretty
`better-ccflare_DEBUG`	Enable debug mode (1/0) - enables console output	0

Pricing and Features

Variable	Description	Default
`CF_PRICING_REFRESH_HOURS`	Pricing cache duration	24
`CF_PRICING_OFFLINE`	Offline mode flag (1/0)	0

Troubleshooting

Common Issues

OAuth Authentication Fails

Problem: Browser doesn't open or OAuth callback fails

Solutions:

Ensure default browser is configured
Check firewall settings for localhost:7856
Manually copy OAuth URL from terminal
Verify network connectivity

Account Shows as "Expired"

Problem: Token status shows expired

Solutions:

Remove and re-add the account
Check system time synchronization
Verify OAuth session hasn't exceeded 5-hour limit

Rate Limit Errors

Problem: Accounts hitting rate limits frequently

Solutions:

Add more accounts to the pool
Increase session duration for less frequent switching
Implement request throttling in client code
Monitor usage with bun cli list

Database Errors

Problem: "Database is locked" or corruption errors

Solutions:

Stop all better-ccflare processes
Check file permissions on database

Backup and recreate if corrupted:

cp ~/.config/better-ccflare/better-ccflare.db ~/.config/better-ccflare/better-ccflare.db.backup
rm ~/.config/better-ccflare/better-ccflare.db

Debug Mode

Enable detailed logging for troubleshooting:

# Enable debug logging
export BETTER_CCFLARE_DEBUG=1
export LOG_LEVEL=DEBUG

# Run with verbose output
bun run cli --list

# Stream debug logs
bun run cli --logs

Getting Support

Check existing documentation in /docs
Review debug logs for detailed error messages
Ensure all dependencies are up to date
File an issue with reproduction steps

Best Practices

Regular Maintenance
- Clear history periodically to manage database size
- Reset stats monthly for accurate metrics
- Monitor account health with regular bun run cli --list commands
- Use bun run cli --analyze to optimize database performance
Account Management
- Use descriptive account names
- Distribute load across multiple accounts
- Use account priorities to control load distribution:
  - Set lower priority numbers for premium or preferred accounts
  - Use higher priority numbers for backup or development accounts
  - Adjust priorities temporarily for specific workloads
- Pause accounts proactively when approaching rate limits
Security
- Protect configuration directory permissions
- Don't share OAuth tokens or session data
- Rotate accounts periodically
- Monitor logs with bun run cli --logs for suspicious activity
Performance
- Use accounts with higher rate limits for heavy workloads
- Implement client-side retry logic
- Monitor rate limit patterns with bun run cli --stats
- Run server with bun run cli --serve for production use

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

better-ccflare CLI Documentation

Table of Contents

Installation and Setup

Prerequisites

Installation

First-time Setup

Global Options and Help

Getting Help

Help Output Format

Command Reference

Account Management

--add-account <name>

--list

--remove <name>

--pause <name>

--force-reset-rate-limit <name>

--resume <name>

Account Priorities

--set-priority <name> <priority>

Statistics and History

--stats

--reset-stats

--clear-history

System Commands

--analyze

--repair-db

Default Behavior

Server and Monitoring

--serve

--logs [N]

Usage Examples

Basic Account Setup

Server Operations

Managing Rate Limits

Maintenance Operations

Automation Examples

Configuration

Configuration File Location

macOS/Linux

Windows

Configuration Structure

Database Location

Environment Variables

Core Configuration

Load Balancing

Retry Configuration

Session Management

Logging and Debugging

Pricing and Features

Troubleshooting

Common Issues

OAuth Authentication Fails

Account Shows as "Expired"

Rate Limit Errors

Database Errors

Debug Mode

Getting Support

Best Practices

`--add-account <name>`

`--list`

`--remove <name>`

`--pause <name>`

`--force-reset-rate-limit <name>`

`--resume <name>`

`--set-priority <name> <priority>`

`--stats`

`--reset-stats`

`--clear-history`

`--analyze`

`--repair-db`

`--serve`

`--logs [N]`