Skip to content

Commit 7971969

Browse files
authored
feat(nix): add runnable ccusage flake (#1057)
* feat(nix): add runnable ccusage flake Build the Rust CLI with Crane so the repository exposes ccusage as the default Nix package and app. The build uses rust-overlay for the pinned Rust toolchain and injects a locked LiteLLM pricing flake input, avoiding build-time network access in the Nix sandbox. Add a shared jq filter, fallback sync check, and scheduled workflow so the checked-in non-Nix Cargo fallback pricing JSON can be regenerated when the locked LiteLLM input changes. Update the README and docs to document nix run usage and remove bundle-size messaging. * fix(nix): track pricing snapshot changes Emit cargo:rerun-if-changed for the CCUSAGE_PRICING_JSON_PATH file before reading it in build.rs. This keeps Cargo rebuilds correct when Nix supplies a new locked LiteLLM pricing snapshot at the same environment variable name. * docs: reduce nix mentions in guides Keep the Nix quick-start path in getting-started only, while removing the broader Nix installation section and feature-page mention from public docs. * ci: build native unix packages with nix Use nix build for Linux and Darwin native package artifacts so CI can reuse Nix store caching instead of depending on Cargo target cache behavior. Linux now builds the static musl binary through a ccusage-static flake package, preserving the existing portable native package contract. Windows continues to use cargo build because Nix is not part of that runner path. * fix(nix): cross build static linux binaries Use the musl cross package sets for the Linux static package instead of pkgsStatic. The CI build scripts need host executables while Cargo still targets the musl triples for the final binary, and pkgsStatic caused build-script links to mix static flags with dynamic glibc objects. Keep the rust-overlay toolchain target-specific so nix flake evaluation exposes the same ccusage-static package names while avoiding the failed static build-script link path seen in CI. * ci: cache windows cargo builds Windows native package jobs still use Cargo because the Nix build path only replaces Unix package builds. Cache the Cargo registry, git checkout cache, and rust/target directory by runner OS, runner architecture, Cargo.lock, and rust-toolchain.toml so Windows x64 and arm64 builds can reuse dependencies and release artifacts do not pay a cold build cost every run. * ci: keep nix macos binaries portable Darwin native packages now build through Nix, but the resulting binary carried the Nix store install name for libiconv into the npm optional dependency. That works on a Nix-enabled builder but fails on ordinary macOS users and in preview E2E, where the store path is absent. Rewrite the Darwin binary install name to the system libiconv after the final package install. Also extend the perf package URL wait because pkg.pr.new publishing can take longer now that native package dry-runs build all Nix artifacts first. * ci: keep darwin package builds on cargo Darwin npm optional dependency packages already worked when built by Cargo on the GitHub macOS runners. Building those distribution binaries with Nix introduced Nix store dylib references, which made the pkg.pr.new macOS E2E fail outside a Nix environment and risked extra packaging complexity. Limit Nix native package builds to Linux static artifacts, where they replace the uncached musl setup. Darwin and Windows now share the Cargo build path with the same Cargo registry, git, and target cache, while the flake still supports nix run and Nix-built Darwin packages for Nix users.
1 parent 71de950 commit 7971969

16 files changed

Lines changed: 2374 additions & 102 deletions

‎.github/workflows/ccusage-perf.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ jobs:
5454
--large-codex-fixture-dir "$RUNNER_TEMP/ccusage-large-codex-fixture" \
5555
--large-warmup 0 \
5656
--large-runs 1 \
57-
--package-runner-timeout-ms 600000 \
57+
--package-runner-timeout-ms 1800000 \
5858
--output "$RUNNER_TEMP/ccusage-perf-comment.md"
5959
6060
- name: Write job summary

‎.github/workflows/ccusage-rust-perf.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ jobs:
5252
--large-codex-fixture-dir "$RUNNER_TEMP/ccusage-large-codex-fixture" \
5353
--large-warmup 0 \
5454
--large-runs 1 \
55-
--package-runner-timeout-ms 600000 \
55+
--package-runner-timeout-ms 1800000 \
5656
--output "$RUNNER_TEMP/ccusage-rust-perf-comment.md"
5757
5858
- name: Write job summary

‎.github/workflows/ci.yaml‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,11 @@ jobs:
3636
- os: ubuntu-24.04-arm
3737
platform: linux
3838
arch: arm64
39-
rust_target: aarch64-unknown-linux-musl
40-
binary: rust/target/aarch64-unknown-linux-musl/release/ccusage
39+
binary: result/bin/ccusage
4140
- os: ubuntu-24.04
4241
platform: linux
4342
arch: x64
44-
rust_target: x86_64-unknown-linux-musl
45-
binary: rust/target/x86_64-unknown-linux-musl/release/ccusage
43+
binary: result/bin/ccusage
4644
- os: macos-latest
4745
platform: darwin
4846
arch: arm64
@@ -62,20 +60,24 @@ jobs:
6260

6361
steps:
6462
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
65-
- name: Install Linux musl toolchain
63+
- uses: ./.github/actions/setup-nix
6664
if: matrix.platform == 'linux'
67-
run: |
68-
rustup target add "${{ matrix.rust_target }}"
69-
sudo apt-get update
70-
sudo apt-get install -y musl-tools
65+
with:
66+
cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
67+
- name: Cache Cargo build
68+
if: matrix.platform != 'linux'
69+
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
70+
with:
71+
path: |
72+
~/.cargo/registry
73+
~/.cargo/git
74+
rust/target
75+
key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('rust/Cargo.lock', 'rust-toolchain.toml') }}
76+
restore-keys: |
77+
cargo-${{ runner.os }}-${{ runner.arch }}-
7178
- name: Build Linux static binary
7279
if: matrix.platform == 'linux'
73-
env:
74-
CC_aarch64_unknown_linux_musl: musl-gcc
75-
CC_x86_64_unknown_linux_musl: musl-gcc
76-
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER: musl-gcc
77-
CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER: musl-gcc
78-
run: cargo build --manifest-path rust/Cargo.toml --release --bin ccusage --target "${{ matrix.rust_target }}"
80+
run: nix build .#ccusage-static
7981
- name: Verify Linux binary is static
8082
if: matrix.platform == 'linux'
8183
shell: bash
@@ -88,7 +90,7 @@ jobs:
8890
cat "$RUNNER_TEMP/ldd.txt"
8991
grep -Eiq 'not a dynamic executable|statically linked' "$RUNNER_TEMP/ldd.txt"
9092
fi
91-
- name: Build native binary
93+
- name: Build Cargo native binary
9294
if: matrix.platform != 'linux'
9395
run: cargo build --manifest-path rust/Cargo.toml --release --bin ccusage
9496
- run: node apps/ccusage/scripts/stage-native-package.mjs --platform "${{ matrix.platform }}" --arch "${{ matrix.arch }}" --binary "${{ matrix.binary }}"

‎.github/workflows/release.yaml‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,11 @@ jobs:
1616
- os: ubuntu-24.04-arm
1717
platform: linux
1818
arch: arm64
19-
rust_target: aarch64-unknown-linux-musl
20-
binary: rust/target/aarch64-unknown-linux-musl/release/ccusage
19+
binary: result/bin/ccusage
2120
- os: ubuntu-24.04
2221
platform: linux
2322
arch: x64
24-
rust_target: x86_64-unknown-linux-musl
25-
binary: rust/target/x86_64-unknown-linux-musl/release/ccusage
23+
binary: result/bin/ccusage
2624
- os: macos-latest
2725
platform: darwin
2826
arch: arm64
@@ -44,20 +42,24 @@ jobs:
4442
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
4543
with:
4644
fetch-depth: 0
47-
- name: Install Linux musl toolchain
45+
- uses: ./.github/actions/setup-nix
4846
if: matrix.platform == 'linux'
49-
run: |
50-
rustup target add "${{ matrix.rust_target }}"
51-
sudo apt-get update
52-
sudo apt-get install -y musl-tools
47+
with:
48+
cachix-auth-token: ${{ secrets.CACHIX_AUTH_TOKEN }}
49+
- name: Cache Cargo build
50+
if: matrix.platform != 'linux'
51+
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
52+
with:
53+
path: |
54+
~/.cargo/registry
55+
~/.cargo/git
56+
rust/target
57+
key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('rust/Cargo.lock', 'rust-toolchain.toml') }}
58+
restore-keys: |
59+
cargo-${{ runner.os }}-${{ runner.arch }}-
5360
- name: Build Linux static binary
5461
if: matrix.platform == 'linux'
55-
env:
56-
CC_aarch64_unknown_linux_musl: musl-gcc
57-
CC_x86_64_unknown_linux_musl: musl-gcc
58-
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER: musl-gcc
59-
CARGO_TARGET_X86_64_UNKNOWN_LINUX_MUSL_LINKER: musl-gcc
60-
run: cargo build --manifest-path rust/Cargo.toml --release --bin ccusage --target "${{ matrix.rust_target }}"
62+
run: nix build .#ccusage-static
6163
- name: Verify Linux binary is static
6264
if: matrix.platform == 'linux'
6365
shell: bash
@@ -70,7 +72,7 @@ jobs:
7072
cat "$RUNNER_TEMP/ldd.txt"
7173
grep -Eiq 'not a dynamic executable|statically linked' "$RUNNER_TEMP/ldd.txt"
7274
fi
73-
- name: Build native binary
75+
- name: Build Cargo native binary
7476
if: matrix.platform != 'linux'
7577
run: cargo build --manifest-path rust/Cargo.toml --release --bin ccusage
7678
- run: node apps/ccusage/scripts/stage-native-package.mjs --platform "${{ matrix.platform }}" --arch "${{ matrix.arch }}" --binary "${{ matrix.binary }}"
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: update pricing
2+
3+
on:
4+
schedule:
5+
- cron: '0 3 * * 1'
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: write
10+
pull-requests: write
11+
12+
jobs:
13+
update-pricing:
14+
runs-on: ubuntu-24.04-arm
15+
steps:
16+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
17+
- uses: ./.github/actions/setup-nix
18+
- name: Update LiteLLM pricing input
19+
run: |
20+
nix flake update litellm-pricing
21+
nix run .#update-pricing-fallback
22+
nix flake check
23+
- name: Create pull request
24+
env:
25+
GH_TOKEN: ${{ github.token }}
26+
run: |
27+
if git diff --quiet; then
28+
echo "Pricing snapshot is already up to date."
29+
exit 0
30+
fi
31+
32+
git config user.name "github-actions[bot]"
33+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
34+
35+
branch="automation/litellm-pricing"
36+
git checkout -B "$branch"
37+
git add flake.lock rust/crates/ccusage/src/litellm-pricing-fallback.json
38+
git commit -m "chore(pricing): update LiteLLM snapshot"
39+
git push --force-with-lease origin "$branch"
40+
41+
body="$(printf '%s\n' \
42+
'Updates the locked LiteLLM pricing input and refreshes the non-Nix Cargo fallback pricing JSON.' \
43+
'' \
44+
'Validation:' \
45+
'- nix flake check')"
46+
47+
if gh pr view "$branch" >/dev/null 2>&1; then
48+
printf '%s\n' "$body" | gh pr edit "$branch" --title "chore(pricing): update LiteLLM snapshot" --body-file -
49+
else
50+
printf '%s\n' "$body" | gh pr create --base main --head "$branch" --title "chore(pricing): update LiteLLM snapshot" --body-file -
51+
fi

‎apps/ccusage/README.md‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
<a href="https://socket.dev/api/npm/package/ccusage"><img src="https://socket.dev/api/badge/npm/package/ccusage" alt="Socket Badge" /></a>
88
<a href="https://npmjs.com/package/ccusage"><img src="https://img.shields.io/npm/v/ccusage?color=yellow" alt="npm version" /></a>
99
<a href="https://tanstack.com/stats/npm?packageGroups=%5B%7B%22packages%22:%5B%7B%22name%22:%22ccusage%22%7D%5D%7D%5D&range=30-days&transform=none&binType=daily&showDataMode=all&height=400"><img src="https://img.shields.io/npm/dt/ccusage" alt="NPM Downloads" /></a>
10-
<a href="https://packagephobia.com/result?p=ccusage"><img src="https://packagephobia.com/badge?p=ccusage" alt="install size" /></a>
1110
<a href="https://deepwiki.com/ryoppippi/ccusage"><img src="https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="DeepWiki"></a>
1211
<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
1312
<a href="https://github.com/hesreallyhim/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code" /></a>
@@ -31,12 +30,15 @@ The main CLI tool for analyzing Claude Code, Codex, OpenCode, Amp, and pi-agent
3130

3231
### Quick Start (Recommended)
3332

34-
Thanks to ccusage's incredibly small bundle size ([![install size](https://packagephobia.com/badge?p=ccusage)](https://packagephobia.com/result?p=ccusage)), you can run it directly without installation:
33+
You can run ccusage directly without a global installation:
3534

3635
```bash
3736
# Recommended
3837
bunx ccusage
3938

39+
# Nix
40+
nix run github:ryoppippi/ccusage -- daily
41+
4042
# Alternative package runners
4143
pnpm dlx ccusage
4244
pnpx ccusage
@@ -110,7 +112,6 @@ bunx ccusage monthly --compact # Compact monthly report
110112
- 🏗️ **Claude Instance Support**: Group Claude Code usage by project with `--instances` and filter by specific projects
111113
- 🌍 **Timezone Support**: Configure timezone for date grouping with `--timezone` option
112114
- ⚙️ **Configuration Files**: Set defaults with JSON configuration files, complete with IDE autocomplete and validation
113-
- 🚀 **Ultra-Small Bundle**: Unlike other CLI tools, we pay extreme attention to bundle size - incredibly small even without minification!
114115

115116
## Documentation
116117

@@ -136,6 +137,26 @@ nix develop
136137

137138
This ensures consistent tooling versions across all contributors and CI systems. The development environment is defined in `flake.nix` and automatically activated via direnv when entering the project directory.
138139

140+
### Nix Package
141+
142+
The flake exposes `ccusage` as the default package and app:
143+
144+
```bash
145+
nix run github:ryoppippi/ccusage
146+
nix run github:ryoppippi/ccusage -- codex daily --offline
147+
nix build github:ryoppippi/ccusage
148+
```
149+
150+
Nix builds embed the LiteLLM pricing file from the locked `litellm-pricing` flake input, so sandboxed builds do not fetch pricing at build time. To update the locked pricing snapshot and refresh the non-Nix Cargo fallback JSON:
151+
152+
```bash
153+
nix flake update litellm-pricing
154+
nix run .#update-pricing-fallback
155+
nix flake check
156+
```
157+
158+
The scheduled `update pricing` workflow runs the same commands and opens a PR when the locked input changes.
159+
139160
## Sponsors
140161

141162
### Featured Sponsor

‎docs/guide/getting-started.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ The fastest way to try ccusage is to run it directly without installation:
1717
bunx ccusage
1818
```
1919

20+
```bash [Nix]
21+
nix run github:ryoppippi/ccusage -- daily
22+
```
23+
2024
```bash [npx]
2125
npx ccusage@latest
2226
```

‎docs/guide/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,9 @@ ccusage reads the local usage files that coding CLIs already generate and provid
3636

3737
## Key Features
3838

39-
### 🚀 Ultra-Small Bundle Size
39+
### 🚀 Direct Execution
4040

41-
Unlike many CLI tools, ccusage pays close attention to bundle size. You can run it directly without a global install using `bunx ccusage` (recommended), `pnpm dlx ccusage`, or `npx ccusage@latest`.
41+
You can run ccusage without a global install using `bunx ccusage` (recommended), `pnpm dlx ccusage`, or `npx ccusage@latest`.
4242

4343
### 📊 Usage Views
4444

‎docs/guide/installation.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,13 @@
22

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

5-
## Why No Installation Needed?
5+
## Why Direct Execution Works Well
66

7-
Thanks to ccusage's incredibly small bundle size, you don't need to install it globally. Unlike other CLI tools, we pay extreme attention to bundle size optimization, achieving an impressively small footprint even without minification. This means:
7+
You do not need to install ccusage globally before trying it. Direct package runners work well for ad hoc usage:
88

9-
- ✅ Near-instant startup times
10-
- ✅ Minimal download overhead
11-
- ✅ Always use the latest version
12-
- ✅ No global pollution of your system
9+
- ✅ No global package to manage
10+
- ✅ Easy access to the latest published version
11+
- ✅ Cached package downloads after the first run
1312

1413
## Quick Start (Recommended)
1514

@@ -53,7 +52,7 @@ Here's why runtime choice matters:
5352

5453
## Global Installation (Optional)
5554

56-
While not necessary due to our small bundle size, you can still install ccusage globally if you prefer:
55+
You can install ccusage globally if you prefer a persistent command:
5756

5857
::: code-group
5958

‎flake.lock‎

Lines changed: 29 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)