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. Each value can be one directory or a comma-separated list of directories:

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
PI_AGENT_DIR	pi-agent	~/.pi/agent/sessions

Example:

export CODEX_HOME="/path/to/codex,/archive/codex"
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
ccusage daily

Empty entries and directories that do not exist 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

CCUSAGE_BUN_AUTO_RUN

When the published CLI starts under Node.js and finds bun in PATH, it automatically re-runs the bundled entrypoint with Bun. Disable this if you need to force Node.js:

CCUSAGE_BUN_AUTO_RUN=0 ccusage daily

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|PI_AGENT|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