CLI Reference

Complete command reference for clankerwatch, generated from the program itself.

clankerwatch publishes Claude Code subscription usage on the D-Bus session bus for a KDE Plasma widget: the current 5-hour session, the weekly limits, their reset times, and extra usage.

It reads Claude Code’s login without ever refreshing or writing it, calls the Anthropic usage endpoint at most every five minutes while Claude Code is active, and adopts Claude Code’s own cached result whenever that is newer. Desktop notifications fire when usage crosses the alert thresholds.

Settings come from ~/.config/clankerwatch/config.yaml. An environment variable overrides the file, and a flag overrides both.

Commands

The systemd user unit runs serve, so you rarely run it yourself. status is the first thing to check when the widget shows something unexpected.

Examples

Run the daemon, as the systemd user unit does.

clankerwatch serve

Print the settings and the snapshot the daemon would publish, offline.

clankerwatch status

Replay canned states for widget development.

clankerwatch demo --notify ""

Global options

Every command accepts these settings flags. A flag overrides its environment variable, which overrides the settings file. See Configuration for the details.