Installation
You can run ccusage directly or install it globally.
Quick Start (Recommended)
Run ccusage directly with a package runner:
bunx ccusagepnpm dlx ccusagenpx ccusage@latestbunx -p https://pkg.pr.new/ccusage@<pr-number-or-commit-sha> ccusage --offlineGlobal Installation (Optional)
You can install ccusage globally if you prefer a persistent command:
npm install -g ccusagebun install -g ccusageyarn global add ccusagepnpm add -g ccusageAfter global installation, run commands directly:
ccusage daily
ccusage monthly --breakdown
ccusage blocks --activeDevelopment Installation
For development or contributing to ccusage:
# Clone the repository
git clone https://github.com/ccusage/ccusage.git
cd ccusage
# Allow direnv to load the Nix dev shell
direnv allowThe Nix dev shell provides the pinned pnpm, Rust toolchain, GitHub CLI, git hooks, package tooling, and project utilities. Run project tasks with just:
# Format the tree
just fmt
# Run tests
just test
# Run static checks
just check
# Build the documentation site and lint the npm package manifest
just build
# Build the native CLI in release mode
cargo build --manifest-path rust/Cargo.toml --release --bin ccusageYou can also run the package directly from source:
just ccusage::start daily
just ccusage::start monthly --jsonRuntime Requirements
Node.js
- Needed when using Node-based package runners or npm-style global installs
- The package launcher also supports Bun
Native Binary
The npm launcher runs the native binary for your operating system and architecture. The package provides binaries for macOS, Linux, and Windows on x64 and arm64.
Verification
After installation, verify ccusage is working:
# Check version
ccusage --version
# Run help command
ccusage --help
# Test with daily report
ccusage dailyUpdating
Direct Execution (npx/bunx)
An unversioned package name can reuse a locally installed or cached copy. When the runner needs to fetch ccusage from the registry, it uses the default latest dist-tag. To request that dist-tag explicitly, run npx ccusage@latest or bunx ccusage@latest. For reproducible runs, specify an exact version.
Global Installation
# Update with npm
npm update -g ccusage
# Update with bun
bun update -g ccusageCheck Current Version
ccusage --versionUninstalling
Global Installation
npm uninstall -g ccusagebun remove -g ccusageyarn global remove ccusagepnpm remove -g ccusageDevelopment Installation
# Remove cloned repository
rm -rf ccusage/Troubleshooting Installation
Permission Errors
If you get permission errors during global installation:
# Use npx instead of global install
npx ccusage@latest
# Or configure npm to use a different directory
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATHNetwork Issues
If installation fails due to network issues:
# Try with different registry
npm install -g ccusage --registry https://registry.npmjs.org
# Or use bunx for offline-capable runs
bunx ccusageVersion Conflicts
If you have multiple versions installed:
# Check which version is being used
which ccusage
ccusage --version
# Uninstall and reinstall
npm uninstall -g ccusage
npm install -g ccusage@latestNext Steps
After installation, check out:
- Getting Started Guide - Your first usage report
- Configuration - Customize ccusage behavior
- Daily Usage - Understand daily usage patterns