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.

CLAUDE_CONFIG_DIR

Specifies where ccusage should look for Claude Code data. This is the most important environment variable for ccusage.

Single Directory

Set a single custom Claude data directory:

ccusage daily

Multiple Directories

Set multiple directories (comma-separated) to aggregate data from multiple sources:

ccusage daily

When multiple directories are specified, ccusage automatically aggregates usage data from all valid locations.

Default Behavior

When CLAUDE_CONFIG_DIR is not set, ccusage automatically searches in:

1. ~/.config/claude/projects/ (new default, Claude Code v1.0.30+)
2. ~/.claude/projects/ (legacy location, pre-v1.0.30)

Data from all valid directories is automatically combined.

::: info Directory Change The directory change from ~/.claude to ~/.config/claude in Claude Code v1.0.30 was an undocumented breaking change. ccusage handles both locations automatically for backward compatibility. :::

Use Cases

Development Environment

# Set in your shell profile (.bashrc, .zshrc, config.fish)

Multiple Claude Installations

# Aggregate data from different Claude installations

Team Shared Directory

# Use team-shared data directory

CI/CD Environment

# Use specific directory in CI pipeline

ccusage daily --json > usage-report.json

LOG_LEVEL

Controls the verbosity of log output. ccusage uses consola for logging under the hood.

Log Levels

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:

ccusage daily  # Runs in offline mode

NO_COLOR

Disable colored output (standard CLI convention):

ccusage daily  # No color formatting

FORCE_COLOR

Force colored output even when piping:

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

ccusage daily

Permanent (Shell Profile)

Add to your shell configuration file:

Bash (~/.bashrc)

Zsh (~/.zshrc)

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

set -x CLAUDE_CONFIG_DIR "$HOME/.config/claude"
set -x LOG_LEVEL 3

PowerShell (Profile.ps1)

$env:CLAUDE_CONFIG_DIR = "$env:USERPROFILE\\.config\\claude"
$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

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