alice.mosphere.at / ccusage
npx ccusage
Star
Fork 0
Watch
ccusage docs guide installation.md
4.7 kB
Markdown
at main

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

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

::: code-group

bunx ccusage

pnpm dlx ccusage

npx ccusage@latest

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

:::

::: tip Speed Recommendation We recommend bunx for everyday use. It caches the downloaded package, so repeated runs are faster after the first launch. :::

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

Global Installation (Optional) #

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

::: code-group

npm install -g ccusage

bun install -g ccusage

yarn global add ccusage

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/ccusage/ccusage.git
cd ccusage

# Allow direnv to load the Nix dev shell
direnv allow

The 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 distribution
just build

You can also run the package directly from source:

pnpm --filter ccusage start daily
pnpm --filter ccusage start monthly --json

Runtime Requirements #

Node.js #

  • Needed when using Node-based package runners or npm-style global installs
  • Use Bun for direct execution when available

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 #

::: code-group

npm uninstall -g ccusage

bun remove -g ccusage

yarn global remove ccusage

pnpm remove -g ccusage

:::

Development Installation #

# Remove cloned repository
rm -rf ccusage/

Troubleshooting Installation #

Permission Errors #

If you get permission errors during global installation:

::: code-group

# 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

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