October 20, 2026 · CLI · 4 min read

bum report: your AI usage in a terminal, for people and for agents

#cli#ai-agents#claude-code

Not every machine has a tray. You might be on a server over SSH, inside WSL, or working with an AI agent that cannot click a window. bum report is Bumeter's Overview screen as one command: your limits, what burned the quota, and what to do about it, as text for you or JSON for a script.

One command

bum report              # the last 7 days
bum report --days 1     # today only
bum report --tool kiro  # one tool
bum report --json       # the same numbers, for scripts and agents

Here is what it prints (the numbers are an example):

It ranks tools, projects and turns by quota-weighted tokens, like the app, because raw totals are mostly cheap cache reads (the context post explains the weights). When a finding names a session the CLI can open, the report adds the exact bum session <id> to run next.

It works without the app

The desktop app keeps the database up to date while it runs. bum report does not need it:

• If the app (or bum daemon) is running, the report reads the database it keeps, read-only, and returns at once.
• If nothing is running, it reads the logs itself first (it prints bum: reading the logs (the app is not running)…), then reports.

The two never fight over the database: only one process may write it at a time, guarded by a lock file, and readers always open it read-only.

The rest of the CLI

The commands that list things take --json, and the commands that change things print what they did and how to undo it.

Built to be used by agents

An AI coding agent is now one of the most likely users of a command line tool. A few rules make bum safe and useful for one:

• JSON that matches the text. --json prints the same numbers the text view shows, built by the same function, so an agent and a person never see different answers.
• Nothing changes by accident. bum skills disable without --yes prints the plan, changes nothing and exits with an error code. An agent that runs a command to "see what it does" learns what it would do, and that is all.
• Exit codes mean something. bum skills audit fails only when there is a high-severity finding, so a script can gate on it. A command that changed nothing does not report success.
• Everything can be undone. Every change has a journal id and bum skills undo <id>.

In practice that means you can ask an agent "why did I run out of Claude quota this week?" and let it run bum report --json, or "which of my skills are never used?" and let it run bum skills list --json, with no risk that it reorganises your setup while answering.

Getting bum

bum ships with the Bumeter app on every platform. The Linux packages put it in /usr/bin, the Homebrew cask links it into Homebrew's bin, and the Windows installer adds it to your user PATH, so it works in a new terminal right after installing.