Quick start

curl -fsSL https://raw.githubusercontent.com/SophanaSok/ai-usage-tui/main/scripts/install.sh | sh

ai-usage-tui

scripts/install.sh picks the archive for your platform — on Linux the static build, so neither Alpine’s musl nor an older glibc is a reason for it not to start; --libc gnu takes the glibc one — verifies it against the release’s published SHA-256 checksums, and installs into ~/.local/bin — --dir PATH to choose somewhere else, --version vX.Y.Z to pin a release. It refuses to install anything it could not verify, and names the source build on a platform with no prebuilt binary.

Re-run it to upgrade. It names the version it replaced, and — the case that actually bites — warns when a copy installed by some other channel sits earlier on your PATH and will go on being the one that runs. --doctor names the channel each copy came from.

Manual download

If you would rather not pipe a script into your shell:

VERSION=v1.1.0
case "$(uname -s)-$(uname -m)" in
  Linux-x86_64)  SLUG=x86_64-linux-musl   ;;
  Linux-aarch64) SLUG=aarch64-linux-musl  ;;
  Darwin-arm64)  SLUG=aarch64-macos  ;;
  Darwin-x86_64) SLUG=x86_64-macos   ;;
  *) SLUG=""; echo "No prebuilt binary for $(uname -s)-$(uname -m) — build from source instead." ;;
esac

if [ -n "$SLUG" ]; then
  # Unpacked into a scratch directory: the archive also contains README.md and
  # LICENSE, so extracting it in place would overwrite yours.
  TMP="$(mktemp -d)"
  curl -fsSL "https://github.com/SophanaSok/ai-usage-tui/releases/download/${VERSION}/ai-usage-tui-${VERSION}-${SLUG}.tar.gz" \
    | tar xz -C "$TMP"
  mkdir -p ~/.local/bin
  install -m 755 "$TMP/ai-usage-tui" ~/.local/bin/   # or sudo install ... /usr/local/bin/
  rm -rf "$TMP"
fi

ai-usage-tui

If the last line reports command not found, ~/.local/bin is not on your PATH; add export PATH="$HOME/.local/bin:$PATH" to your shell’s rc file.

If OpenCode stores its database elsewhere:

ai-usage-tui --db /path/to/opencode.db

# Equivalent environment-variable form
OPENCODE_DB_PATH=/path/to/opencode.db ai-usage-tui

See Installation for macOS and Windows archives, package managers, and source builds.

Installation

Prebuilt release

Download the archive for your platform from GitHub Releases, extract it, and place ai-usage-tui (or ai-usage-tui.exe) on your PATH. Checksums are published with each release.

Match the archive to your machine’s architecture. Every published binary is verified with file during the release build to confirm it is the architecture its name claims, so an x86_64 archive really does contain an x86_64 binary and will not run on Apple Silicon.

On Linux, take the static archive unless you have a reason not to. The glibc build needs a glibc at least as new as the machine that linked it — 2.39, through v0.20.0 — so it does not start on Debian 12, Ubuntu 22.04 or RHEL 9, and cannot be loaded at all on Alpine. The static one is a single file with nothing to resolve at load time, and the release build runs it on a bare Alpine before publishing it. The .deb and .rpm carry the static binary for the same reason, and are installed and run on Debian 11, Ubuntu 20.04, Rocky 8 and Fedora in the release build. Static archives exist from v1.0.0.

macOS example (Apple Silicon — use x86_64-macos on an Intel Mac):

VERSION=v1.1.0
TMP="$(mktemp -d)"
curl -fsSL "https://github.com/SophanaSok/ai-usage-tui/releases/download/${VERSION}/ai-usage-tui-${VERSION}-aarch64-macos.tar.gz" \
  | tar xz -C "$TMP"
sudo install -m 755 "$TMP/ai-usage-tui" /usr/local/bin/
rm -rf "$TMP"

The archive carries README.md and LICENSE alongside the binary, so unpack it into a scratch directory as above rather than extracting it where you stand.

Gatekeeper. The macOS binaries are neither signed nor notarized — the project has no Apple Developer ID. Downloading the archive in a browser marks it com.apple.quarantine, and the extracted binary is then refused with “cannot be opened because the developer cannot be verified”. Clear it once:

xattr -d com.apple.quarantine /usr/local/bin/ai-usage-tui

Downloading with curl, as above, does not set the attribute, and needs no such step.

Linux package example:

sudo dpkg -i ai-usage-tui-v1.1.0-amd64.deb      # Debian/Ubuntu
sudo rpm -i ai-usage-tui-v1.1.0-amd64.rpm       # Fedora/RHEL

On Windows, extract the zip and add the directory containing ai-usage-tui.exe to your PATH.

Verifying a download

Every release publishes checksums.txt, and the install script refuses an archive that does not match it. That proves the download is the file the release lists. It cannot prove more, because the checksums come from the same place as the archive.

Releases after v0.19.0 also carry a build attestation: a statement signed by the release workflow’s own identity, kept by GitHub apart from the release’s files, that this exact file was built by this repository’s release.yml at the tagged commit. With the GitHub CLI:

gh attestation verify ai-usage-tui-"$VERSION"-x86_64-linux.tar.gz \
  --repo SophanaSok/ai-usage-tui \
  --signer-workflow SophanaSok/ai-usage-tui/.github/workflows/release.yml \
  --source-ref "refs/tags/$VERSION"

Each flag closes a door: the repository, the workflow — no other workflow’s attestation will do — and the tag, because the release workflow can also be run by hand on a branch, and what that builds is attested as built from the branch.

It covers every archive and every .deb and .rpm. The install script runs the same check whenever gh is there to run it. Nothing is refused for the lack of a tool — no gh, one too old, or not signed in is reported as “not checked” and the install goes on — but a check that fails refuses the download, because for an attested release that is the case the attestation exists to catch. --require-attestation makes “not checked” fatal too; --no-attestation skips the step.

Each release also ships a bill of materials, ai-usage-tui-<tag>.cdx.json (CycloneDX): every crate any released target links, with its version, licence and registry checksum. It is attested against the same files, so gh attestation verify … --predicate-type https://cyclonedx.org/bom confirms that the list belongs to the binary you have.

Shell completions and the man page

The .deb and .rpm install both. Every archive carries them under completions/ — the Windows zip a PowerShell script, completions/_ai-usage-tui.ps1, to dot-source from your $PROFILE — beside the man page. From cargo install, or to match a newer binary, generate them yourself — they come from the parser itself, so they cannot describe a flag that does not exist:

ai-usage-tui --completions bash > ~/.local/share/bash-completion/completions/ai-usage-tui
ai-usage-tui --completions zsh  > ~/.zfunc/_ai-usage-tui
ai-usage-tui --completions fish > ~/.config/fish/completions/ai-usage-tui.fish

ai-usage-tui --man > ~/.local/share/man/man1/ai-usage-tui.1

bash, zsh, fish, elvish and powershell are supported.

Package managers

Homebrew and Scoop manifests are rendered at release time from the real artifact names and checksums, and pushed to a tap and a bucket:

brew install sophanasok/tap/ai-usage-tui        # macOS and Linux

scoop bucket add sophanasok https://github.com/SophanaSok/scoop-bucket
scoop install ai-usage-tui                      # Windows

On Arch, an ai-usage-tui-bin PKGBUILD in AUR format is rendered at release time and attached to each release; like the Chocolatey package below it is not submitted to the AUR, so install it from the release rather than with an AUR helper. It installs the published Linux tarball for x86_64 or aarch64 rather than compiling, and places the binary, the man page, the licence and all three shell completions where pacman expects them:

curl -fLO https://github.com/SophanaSok/ai-usage-tui/releases/latest/download/PKGBUILD
makepkg -si                                     # Arch, x86_64 and aarch64

A Chocolatey package is rendered at release time too and attached to each release, but it is not pushed to the Chocolatey gallery; choco pack the attached ai-usage-tui.nuspec and its tools/ directory to install from it.

Build or install from source

Install the stable Rust toolchain with rustup, then:

# From crates.io
cargo install ai-usage-tui --locked

# Prebuilt binary via crates.io metadata, without compiling
cargo binstall ai-usage-tui

Or build from a clone:

git clone https://github.com/SophanaSok/ai-usage-tui
cd ai-usage-tui

# Install to Cargo's binary directory
cargo install --path . --locked

# Or build without installing
cargo build --release --locked
./target/release/ai-usage-tui

Uninstalling. ai-usage-tui --uninstall takes back what the tool put elsewhere – its hook and status line out of Claude Code’s settings.json, its caches out of the data directory – and prints the paths of the journal and the config file with the rm that would delete them, without running it: those are your data. Then remove the binary the way it was installed; --doctor names the channel and the path.