burntop CLI

Track your AI tool usage and compete on the leaderboard - right from your terminal

What is burntop?

burntop is a gamified AI usage tracking platform for developers. It automatically tracks your usage across multiple AI coding tools, giving you insights into your productivity while making it fun through achievements, streaks, and global leaderboards.

The CLI tool runs locally on your machine, scanning usage data from popular AI coding assistants and syncing it to your burntop.dev profile.

Features

• Automatic Detection - Scans local data from Claude Code, Cursor, Gemini CLI, Aider, and Continue
• Rich Statistics - View token usage, costs, model breakdowns, and trends
• Achievements - Track your progress and unlock badges
• Leaderboards - See how you rank globally
• Streak Tracking - Keep your daily usage streak alive
• Privacy First - All data processing happens locally, you control what gets synced

Installation

Note: The CLI requires bun to be installed on your system, as it uses bun-specific features for SQLite parsing.

Quick Install (Recommended)

curl -fsSL https://burntop.dev/install.sh | bash

Or with wget:

wget -qO- https://burntop.dev/install.sh | bash

Install via bun

bun add -g @burntop/cli

Install via npm

npm install -g @burntop/cli

Note: While you can install via npm, you still need bun installed to run the CLI.

Install via pnpm

pnpm add -g @burntop/cli

Note: While you can install via pnpm, you still need bun installed to run the CLI.

Install via Homebrew (macOS/Linux)

Once the tap is published to GitHub:

brew tap burntop/burntop
brew install burntop

Or install directly from the formula:

brew install burntop/burntop/burntop

Note: Homebrew will automatically install bun as a dependency.

Quick Start

1. Authenticate with burntop.dev

burntop login

You'll be prompted for your email and password. Once complete, your credentials are stored in ~/.config/burntop/credentials.json.

2. View your local AI usage

burntop stats

This shows you detailed statistics from your local AI usage data.

3. Sync your data to the cloud

burntop sync

Your usage data is now on burntop.dev! Visit your profile to see detailed stats, achievements, and your leaderboard position.

Commands

burntop (default: stats)

Show detailed AI usage statistics from your local machine.

burntop                        # Show all stats
burntop stats                  # Explicit stats command
burntop stats --verbose        # Show additional details
burntop stats --source claude-code  # Only show Claude Code stats
burntop stats --period week    # Show stats for this week (day, week, month, all)

burntop login

Authenticate with your burntop.dev account.

burntop login

burntop logout

Clear stored credentials and log out.

burntop logout

burntop sync

Upload your local AI usage data to burntop.dev.

burntop sync                   # Sync all sources
burntop sync --verbose         # Show detailed sync progress
burntop sync --source aider    # Only sync Aider data
burntop sync --dry-run         # Preview what would be synced without uploading

Supported AI Tools

The CLI automatically detects and parses usage data from:

Don't see your tool? Open an issue and we'll add it!

Configuration

Configuration is stored in ~/.config/burntop/:

~/.config/burntop/
├── credentials.json    # OAuth tokens (keep secure!)
└── config.json         # User preferences

Environment Variables

• BURNTOP_API_URL - Override the API endpoint (default: https://burntop.dev)
  • For local development: export BURNTOP_API_URL=http://localhost:8000
  • The CLI will use the FastAPI backend at /api/v1/* endpoints

Privacy & Security

• Local First: All scanning and processing happens on your machine
• Opt-in Sync: Data is only uploaded when you run burntop sync
• Secure Storage: Credentials are stored locally with file permissions 600
• No Tracking: The CLI doesn't phone home or send telemetry
• Open Source: Inspect the code yourself

Troubleshooting

Prerequisites

The CLI requires bun to be installed. Install it from bun.sh:

curl -fsSL https://bun.sh/install | bash

Command not found after installation

Add the global bin directory to your PATH:

For bun:

export PATH="$HOME/.bun/bin:$PATH"

For npm:

export PATH="$(npm prefix -g)/bin:$PATH"

For pnpm:

export PATH="$HOME/.local/share/pnpm:$PATH"

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist.

No data found

Make sure you've used one of the supported AI tools recently. The CLI looks for data in standard locations:

burntop stats --verbose    # See what's being scanned

Authentication issues

If burntop login fails, try:

1. Clear existing credentials: burntop logout
2. Log in again: burntop login
3. Check your internet connection
4. Ensure you're using the latest version: npm update -g @burntop/cli

Sync errors

If sync fails:

burntop sync --dry-run    # Test without uploading
burntop stats --verbose   # Check local data

Development

Building from source

git clone https://github.com/burntop/burntop.git
cd burntop/packages/cli
bun install
bun run build

Testing locally

There are several ways to test the CLI during development:

1. Run directly (without global install)

bun run test:local [command] [args]

This builds the CLI and runs it directly from ./dist/index.js. Example:

bun run test:local stats
bun run test:local --help

2. Link globally (recommended for full testing)

Install the CLI globally from your local development directory:

bun run link

Now you can use burntop command anywhere on your system, and it will use your local development version:

burntop stats
burntop login
burntop --help

When you make changes, rebuild to see them:

bun run build
burntop stats  # Now uses updated code

To unlink when done:

bun run unlink

3. Watch mode (for rapid development)

For rapid iteration without linking:

bun run dev    # Watch mode - rebuilds on file changes

Then in another terminal:

./dist/index.js stats  # Run the CLI directly

Testing with Local Backend

To test the CLI against a local FastAPI backend:

1. Start the FastAPI backend (in packages/backend):

cd packages/backend
uv run uvicorn src.app.main:app --reload

2. Set the API URL environment variable:

export BURNTOP_API_URL=http://localhost:8000

3. Run CLI commands:

burntop login    # Authenticate with local backend
burntop sync     # Sync to local backend

The CLI will now connect to http://localhost:8000/api/v1/* endpoints instead of production.

Contributing

Contributions are welcome! Please see the Contributing Guide.

To add a new parser for an AI tool:

1. Create src/parsers/your-tool.ts
2. Implement the Parser interface from src/parsers/types.ts
3. Add tests
4. Submit a PR

License

MIT © burntop

Links

• burntop.dev - Web platform
• Documentation - Full docs
• Issues - Bug reports
• Discord - Community

Made with fire by developers, for developers