Skip to content

CLI Reference

Push your Claude Code and Codex usage stats to Straude.

npx straude@latest

Quick Start

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

Commands

straude or straude push

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

straude login

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

straude status

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

straude auto

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

straude 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

    Collect usage without submitting it.

  • --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://straude.com.

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 straude push once per day at a set time. Survives reboots and terminal closures.

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

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

A wrapper script at ~/.straude/auto-push.sh captures your PATH at enable-time and falls back through straude → bunx → npx to find the CLI. Logs are written to ~/.straude/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 straude push after every Claude Code session. No background process, no crontab — just a JSON entry.

# Enable hooks-based auto-push
straude --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)
straude --no-auto

# Check which mechanism is active
straude auto

# View scheduler logs (scheduler only)
straude auto logs

Smart Sync

When you run straude 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 uses one bundled ccusage collector. It includes all 16 sources supported by the current release:

  • Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-agent, Goose, OpenClaw, Kilo, Kimi, Qwen Code, GitHub Copilot CLI, Gemini CLI, and Grok Build CLI.

See the ccusage source support guide. Antigravity and ZCode support is not in the released version bundled here. Mistral Vibe is not currently supported by ccusage. The server deduplicates repeated dates safely.

Configuration

All state lives in ~/.straude/:

  • 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.straude.auto-push.plist. On Linux, a tagged entry is added to your crontab.

Troubleshooting

Failed to start login: Rate limit check failed

This means Straude could not complete its server-side rate-limit check before starting the browser login flow. It is usually not caused by your browser, saved token, or local ~/.straude/config.json.

  1. Retry with the latest CLI: npx straude@latest login.
  2. If you use --api-url, confirm it points to the Straude server you intend to use.
  3. Wait a minute and retry. If the error still appears against https://straude.com, treat it as a Straude service issue and report the exact command and timestamp.

Examples

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

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

# Push last 3 days
straude --days 3

# Collect usage without submitting it
straude --dry-run

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

# Check your stats
straude status

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

Global Flags

  • --help, -h

    Show the help text.

  • --version, -v

    Print the CLI version.