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:

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
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
COPILOT_OTEL_FILE_EXPORTER_PATH	Copilot CLI	Explicit .jsonl file
GEMINI_DATA_DIR	Gemini CLI	~/.gemini/tmp

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 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 COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
export GEMINI_DATA_DIR="/path/to/gemini/tmp,/archive/gemini/tmp"
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|HERMES|PI_AGENT|GOOSE|KILO|COPILOT|GEMINI|CCUSAGE|LOG_LEVEL"

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

Related Documentation

• Command-Line Options - CLI arguments and flags
• Configuration Files - JSON configuration files
• Configuration Overview - Complete configuration guide