Skip to content

CLI Reference

Push your Claude Code and Codex usage stats to Blaug.

npx blaug-cli@latest

Quick Start

  1. Run npx blaug-cli@latest— this logs you in and pushes today's stats in one step.
  2. Your profile is live at blaug.app/u/your-username.
  3. Enable daily auto-push: blaug --auto

Commands

blaug or blaug push

Sync your usage data. If you're not logged in, opens a browser to authenticate first. This is the default command — running blaug with no arguments does the same thing.

blaug login

Authenticate with Blaug via browser. Opens an OAuth flow and polls for completion (times out after 5 minutes). Credentials are saved to ~/.blaug/config.json.

blaug status

Show your current streak, weekly spend, leaderboard rank, and shareable profile URL.

blaug auto

Show auto-push status — whether it's enabled, the scheduled time, and which scheduler is active.

blaug auto logs

Print the last 50 lines of the auto-push log. Useful for checking if scheduled pushes are running.

Push Options

  • --date YYYY-MM-DDstring

    Push a specific date. Must be within the last 7 days and not in the future.

  • --days Nnumber

    Push the last N days. Capped at 7.

  • --dry-run

    Preview what would be pushed without sending anything to the server.

  • --timeout Nseconds

    Subprocess timeout for data collection. Default: 240.

  • --auto

    Enable daily auto-push via OS scheduler (launchd on macOS, cron on Linux).

  • --auto hooks

    Enable auto-push via Claude Code SessionEnd hook. Pushes after every coding session instead of on a schedule.

  • --time HH:MMstring

    Set the auto-push time. Use with --auto (scheduler only). Default: 21:00.

  • --no-auto

    Disable auto-push and remove the scheduler entry.

  • --api-url URLstring

    Override the API endpoint. For development use. Default: https://blaug.app.

Auto-Push

Auto-push keeps your stats in sync without manual runs. There are two mechanisms:

OS Scheduler (default)

Installs a system scheduler (launchd on macOS, cron on Linux) that runs blaug push once per day at a set time. Survives reboots and terminal closures.

# Enable at the default time (9 PM)
blaug --auto

# Enable at a custom time
blaug --auto --time 14:30

A wrapper script at ~/.blaug/auto-push.sh captures your PATH at enable-time and falls back through blaug → bunx → npx to find the CLI. Logs are written to ~/.blaug/auto-push.log and rotated at 1 MB. Windows is not supported.

Claude Code Hook

Adds a SessionEnd hook to ~/.claude/settings.json that runs blaug push after every Claude Code session. No background process, no crontab — just a JSON entry.

# Enable hooks-based auto-push
blaug --auto hooks

Codex hook support is planned. The Codex CLI currently only offers a per-turn Stophook, not a session-end event. We'll add Codex support once they ship their equivalent of SessionEnd.

Managing auto-push

# Disable (works for both mechanisms)
blaug --no-auto

# Check which mechanism is active
blaug auto

# View scheduler logs (scheduler only)
blaug auto logs

Smart Sync

When you run blaug with no date flags, it figures out what to sync automatically:

  • First run: backfills the last 3 days.
  • Already pushed today: re-syncs today only (picks up new sessions).
  • Gap ≤ 7 days: syncs from your last push date through today.
  • Gap > 7 days: backfills the most recent 7 days (the max window).

Data Sources

The CLI collects data from two sources in parallel:

  • ccusage — Claude Code session data (cost, tokens, models).
  • @ccusage/codex — Codex usage data (same schema).

Entries are merged by date. If one source is unavailable, the other is used alone. The server deduplicates — pushing the same date twice is safe.

Configuration

All state lives in ~/.blaug/:

  • config.json — auth token, username, device ID, auto-push settings. Permissions are set to owner-only (0600).
  • auto-push.sh — generated wrapper script for the scheduler.
  • auto-push.log — output from scheduled runs.

On macOS, the launchd plist is written to ~/Library/LaunchAgents/com.blaug.auto-push.plist. On Linux, a tagged entry is added to your crontab.

Examples

# First-time setup — login, push, and enable auto-push
npx blaug-cli@latest --auto

# Use Claude Code hooks instead of a scheduler
blaug --auto hooks

# Push last 3 days
blaug --days 3

# Preview without posting
blaug --dry-run

# Push a specific date
blaug --date 2026-03-20

# Check your stats
blaug status

# Change auto-push time to 2 PM
blaug --auto --time 14:00

Global Flags

  • --help, -h

    Show the help text.

  • --version, -v

    Print the CLI version.