alice.mosphere.at / ccusage
npx ccusage
Star
Fork 0
Watch
ccusage docs guide environment-variables.md
7.1 kB
Markdown
at main

Environment Variables #

ccusage supports several environment variables for configuration and customization. Environment variables provide a way to configure ccusage without modifying command-line arguments or configuration files.

Agent Data Directories #

ccusage detects supported data source files from conventional locations by default. Set these variables when your data lives somewhere else. Directory variables can be one directory or a comma-separated list of directories; the Copilot variable points at one explicit JSONL export file, and GROK_HOME accepts a single root only:

Variable Agent Default
CLAUDE_CONFIG_DIR Claude Code ~/.config/claude and ~/.claude
CODEX_HOME Codex ~/.codex
OPENCODE_DATA_DIR OpenCode ~/.local/share/opencode
AMP_DATA_DIR Amp ~/.local/share/amp
DROID_SESSIONS_DIR Droid ~/.factory/sessions
CODEBUFF_DATA_DIR Codebuff ~/.config/manicode
HERMES_HOME Hermes Agent ~/.hermes
PI_AGENT_DIR pi-agent ~/.pi/agent/sessions
GOOSE_PATH_ROOT Goose Standard Goose data roots
OPENCLAW_DIR OpenClaw ~/.openclaw
KILO_DATA_DIR Kilo ~/.local/share/kilo
KIMI_DATA_DIR Kimi ~/.kimi, ~/.kimi-code
QWEN_DATA_DIR Qwen ~/.qwen
COPILOT_OTEL_FILE_EXPORTER_PATH Copilot CLI Explicit .jsonl file
GEMINI_DATA_DIR Gemini CLI ~/.gemini/tmp
GROK_HOME Grok Build CLI ~/.grok

Example:

export CODEX_HOME="/path/to/codex,/archive/codex,/path/to/codex-exec-jsonl"
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
export DROID_SESSIONS_DIR="/path/to/factory/sessions,/archive/factory/sessions"
export CODEBUFF_DATA_DIR="/path/to/manicode,/archive/manicode"
export HERMES_HOME="/path/to/hermes,/archive/hermes"
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
export GOOSE_PATH_ROOT="/path/to/goose,/archive/goose"
export OPENCLAW_DIR="/path/to/openclaw,/archive/openclaw"
export KILO_DATA_DIR="/path/to/kilo,/archive/kilo"
export KIMI_DATA_DIR="/path/to/kimi,/archive/kimi"
export QWEN_DATA_DIR="/path/to/qwen,/archive/qwen"
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
export GEMINI_DATA_DIR="/path/to/gemini/tmp,/archive/gemini/tmp"
export GROK_HOME="/path/to/grok-home"
ccusage daily

Empty entries, directories that do not exist, and missing explicit files are skipped. Duplicate paths are read once.

CLAUDE_CONFIG_DIR #

Specifies where ccusage should look for Claude Code data. See Claude Code for default paths, multiple-directory behavior, and Claude-specific examples.

LOG_LEVEL #

Controls the verbosity of log output.

Log Levels #

Level Value Description Use Case
Silent 0 Errors only Scripts, piping output
Warn 1 Warnings and errors CI/CD environments
Log 2 Normal logs General use
Info 3 Informational logs (default) Standard operation
Debug 4 Debug information Troubleshooting
Trace 5 All operations Deep debugging

Usage Examples #

# Silent mode - only show results
LOG_LEVEL=0 ccusage daily

# Warning level - for CI/CD
LOG_LEVEL=1 ccusage monthly

# Debug mode - troubleshooting
LOG_LEVEL=4 ccusage session

# Trace everything - deep debugging
LOG_LEVEL=5 ccusage blocks

Practical Applications #

Clean Output for Scripts #

# Get clean JSON output without logs
LOG_LEVEL=0 ccusage daily --json | jq '.summary.totalCost'

CI/CD Pipeline #

# Show only warnings and errors in CI
LOG_LEVEL=1 ccusage daily --instances

Debugging Issues #

# Maximum verbosity for troubleshooting
LOG_LEVEL=5 ccusage daily --debug

Piping Output #

# Silent logs when piping to other commands
LOG_LEVEL=0 ccusage monthly --json | python analyze.py

Additional Environment Variables #

CCUSAGE_OFFLINE #

Force offline mode by default:

export CCUSAGE_OFFLINE=1
ccusage daily  # Runs in offline mode

NO_COLOR #

Disable colored output (standard CLI convention):

export NO_COLOR=1
ccusage daily  # No color formatting

FORCE_COLOR #

Force colored output even when piping:

export FORCE_COLOR=1
ccusage daily | less -R  # Preserves colors

Setting Environment Variables #

Temporary (Current Session) #

# Set for single command
LOG_LEVEL=0 ccusage daily

# Set for current shell session
export CODEX_HOME="/path/to/codex,/archive/codex"
ccusage daily

Permanent (Shell Profile) #

Add to your shell configuration file:

Bash (~/.bashrc) #

export CODEX_HOME="$HOME/.codex"
export LOG_LEVEL=3

Zsh (~/.zshrc) #

export CODEX_HOME="$HOME/.codex"
export LOG_LEVEL=3

Fish (~/.config/fish/config.fish) #

set -x CODEX_HOME "$HOME/.codex"
set -x LOG_LEVEL 3

PowerShell (Profile.ps1) #

$env:CODEX_HOME = "$env:USERPROFILE\.codex"
$env:LOG_LEVEL = "3"

Precedence #

Environment variables have lower precedence than command-line arguments but higher than configuration files:

  1. Command-line arguments (highest priority)
  2. Environment variables
  3. Configuration files
  4. Built-in defaults (lowest priority)

Example:

# Environment variable sets offline mode
export CCUSAGE_OFFLINE=1

# But command-line argument overrides it
ccusage daily --no-offline  # Runs in online mode

Debugging #

To see which environment variables are being used:

# Show all environment variables
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|DROID|CODEBUFF|HERMES|PI_AGENT|GOOSE|OPENCLAW|KILO|KIMI|QWEN|COPILOT|GEMINI|GROK|CCUSAGE|LOG_LEVEL"

# Debug mode shows environment variable usage
LOG_LEVEL=4 ccusage daily --debug