Installation

ccusage can be installed and used in several ways depending on your preferences and use case.

Why Direct Execution Works Well

You do not need to install ccusage globally before trying it. Direct package runners work well for ad hoc usage:

• ✅ No global package to manage
• ✅ Easy access to the latest published version
• ✅ Cached package downloads after the first run

Quick Start (Recommended)

The fastest way to use ccusage is to run it directly:

bunx (Recommended)

bunx ccusage

pnpm

pnpm dlx ccusage

npx

npx ccusage@latest

pkg.pr.new preview

bunx -p https://pkg.pr.new/ryoppippi/ccusage@<pr-number> ccusage --offline

Speed Recommendation

We recommend bunx for everyday use. ccusage can run on Node.js 22.11+, but Bun generally starts faster and avoids the slower cold-start path common with npx.

The npm package installs a small JavaScript launcher and the matching native binary package for your platform. Package runners such as bunx cache the downloaded package, so repeated runs reuse the cached native binary; the first run can still include network fetch time.

Performance Comparison

Here's why runtime choice matters:

Runtime	First Run	Subsequent Runs	Notes
bunx	Fast	Instant	Recommended for everyday use
pnpm dlx	Fast	Fast	Good alternative
npx	Slow	Moderate	Widely available, Node.js 22.11+

Global Installation (Optional)

You can install ccusage globally if you prefer a persistent command:

npm

npm install -g ccusage

bun

bun install -g ccusage

yarn

yarn global add ccusage

pnpm

pnpm add -g ccusage

After global installation, run commands directly:

ccusage daily
ccusage monthly --breakdown
ccusage blocks --live

Development Installation

For development or contributing to ccusage:

# Clone the repository
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# Install dependencies
pnpm install

# Run directly from source
pnpm --filter ccusage start daily
pnpm --filter ccusage start monthly --json

Development Scripts

# Run tests
pnpm run test

# Type checking
pnpm typecheck

# Build distribution
pnpm --filter ccusage build

# Lint and format
pnpm run format

Runtime Requirements

Node.js

• Minimum: Node.js 22.11 for the published package
• Recommended: Use Bun for command execution when available
• npx, npm global installs, pnpm, and yarn all use the Node.js runtime unless ccusage re-runs through Bun

Bun

• Minimum: Bun 1.3+
• Recommended: Latest stable release
• Recommended for bunx ccusage and for the fastest warm startup

Verification

After installation, verify ccusage is working:

# Check version
ccusage --version

# Run help command
ccusage --help

# Test with daily report
ccusage daily

Updating

Direct Execution (npx/bunx)

Always gets the latest version automatically.

Global Installation

# Update with npm
npm update -g ccusage

# Update with bun
bun update -g ccusage

Check Current Version

ccusage --version

Uninstalling

Global Installation

npm

npm uninstall -g ccusage

bun

bun remove -g ccusage

yarn

yarn global remove ccusage

pnpm

pnpm remove -g ccusage

Development Installation

# Remove cloned repository
rm -rf ccusage/

Troubleshooting Installation

Permission Errors

If you get permission errors during global installation:

npm

# 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:$PATH

Node Version Managers

# Use nvm
nvm install 22
npm install -g ccusage

# Or use fnm
fnm install 22
npm install -g ccusage

Network 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 ccusage

Version 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@latest

Next Steps

After installation, check out:

• Getting Started Guide - Your first usage report
• Configuration - Customize ccusage behavior
• Daily Usage - Understand daily usage patterns