@usagefleet/cli 1.2.69 → 1.2.71

package/README.md

@@ -1,199 +1,85 @@
 # @usagefleet/cli
 
-Tails the local JSONL logs of Claude Code, Claude Desktop's agent-mode
-(Cowork) sessions, **and** the [pi](https://github.com/badlogic/pi-mono) coding
-agent (`~/.pi/agent/sessions`; only its Anthropic-provider records — usage via
-other providers doesn't touch Claude limits), reporting token usage to a
-UsageFleet server. Read-only on the log files. Zero runtime dependencies
-(Node ≥ 20).
+The UsageFleet collector. It tails the local logs of your Claude agents and
+reports usage to [usagefleet.com](https://usagefleet.com), where it's split
+across your device groups. Read-only on the log files, zero runtime
+dependencies, Node ≥ 20.
 
 ## Install
 
-Two commands, identical on macOS, Linux and Windows. You only need a device
-**token** from the server's Devices page (endpoint defaults to
-`https://usagefleet.com`):
+Get a device **token** from the [Devices](https://usagefleet.com/devices) page,
+then, on that machine:
 
 ```bash
 npm i -g @usagefleet/cli
-usagefleet install --token uf_xxx   # autostart at login; --endpoint <url> when self-hosting
+usagefleet install --token uf_xxx
 ```
 
-In PowerShell chain them with `;` instead of `&&` — Windows PowerShell 5.1 has
-no `&&`.
+Same two commands on macOS, Linux and Windows (in PowerShell chain them with
+`;` — 5.1 has no `&&`). `install` sets the collector to start at login and
+writes `~/.config/usagefleet/config.json` (mode `600`). The dashboard fills in
+within a minute.
 
-Autostart uses launchd (macOS), systemd `--user` (Linux) and Task Scheduler
-(Windows). If `npm i -g` fails with EACCES your global prefix is root-owned:
-either use a Node version manager (nvm, fnm, volta) or
-`npm config set prefix ~/.local` and put `~/.local/bin` on your PATH. Installing
-the collector under `sudo` would run it as the wrong user.
+Running your own server? Add `--endpoint https://track.example.com`.
 
-**Update** happens on its own (see below) or on demand with
-`usagefleet update`. `npm i -g @usagefleet/cli` does the same thing.
+If `npm i -g` fails with EACCES your global prefix is root-owned: use a Node
+version manager (nvm, fnm, volta) or `npm config set prefix ~/.local` with
+`~/.local/bin` on your PATH. Don't install under `sudo` — the collector would
+run as the wrong user.
 
-### Run from source
-
-```bash
-cd apps/cli
-bun install
-bun run src/index.ts status   # or: npm run build && node dist/index.js status
-```
-
-## Configure
-
-Get a device **token** from the server's Devices page, then either:
-
-```bash
-usagefleet install --endpoint https://track.example.com --token uf_xxx
-# writes ~/.config/usagefleet/config.json
-```
-
-That one file (mode `600`) holds everything the CLI persists — your settings
-plus the two machine-managed sections, `state` (per-log tail offsets) and
-`notify` (which alert thresholds already fired). Delete it to start clean.
-`XDG_CONFIG_HOME` is honoured. Installs predating the consolidation are folded
-in automatically from `~/.usagefleet.json`, `~/.usagefleet-state.json` and
-`~/.usagefleet-notify.json` on first write; those files are then unused and
-safe to delete.
-
-Or set env vars (they override the config file):
-
-| Variable | Meaning |
-|----------|---------|
-| `USAGEFLEET_ENDPOINT` | server base URL. Must be `https://` (loopback may be `http://`): it carries the device token on every request |
-| `USAGEFLEET_TOKEN` | device token |
-| `USAGEFLEET_PROJECTS` | override `~/.claude/projects` (Claude Code logs) |
-| `USAGEFLEET_DESKTOP` | override the Claude Desktop agent-mode sessions dir (auto-detected per-OS); set `off`/`0` to skip desktop collection |
-| `USAGEFLEET_PI` | override the pi agent sessions dirs, comma-separated (default `~/.pi/agent/sessions` plus whatever `PI_CODING_AGENT_DIR`/`PI_CODING_AGENT_SESSION_DIR` point at — a service inherits neither, so set this if you relocated pi's agent dir); set `off`/`0` to skip pi collection |
-| `USAGEFLEET_INTERVAL` | watch poll seconds (default 15) |
-| `USAGEFLEET_LIMITS_INTERVAL` | how often to ping for real 5h/weekly limits, seconds (default 300; decoupled from the faster usage poll so the 1-token ping doesn't run every cycle) |
-| `USAGEFLEET_NOTIFY` | desktop notifications on/off (default **on**; set `0`/`false`/`off` to disable) |
-| `USAGEFLEET_NOTIFY_THRESHOLDS` | comma list of utilization % that trigger an alert (default `80,95`) |
-| `USAGEFLEET_BATCH` | records per upload request (default 100, capped at the server's limit of 1000) |
-| `USAGEFLEET_CONFIG` | override the whole config file path (default `~/.config/usagefleet/config.json`) |
-| `USAGEFLEET_UPDATE` | set `0` to turn the self-update check off |
-| `USAGEFLEET_UPDATE_INTERVAL` | seconds between self-update checks (default `21600` = 6h, i.e. 4×/day) |
-| `USAGEFLEET_HOOK` | set `0` to keep the prompt-blocking hook out of `~/.claude/settings.json` |
-
-### Setting the token per shell
-
-**bash / zsh** (macOS, Linux) — one-off for the current session:
-
-```bash
-export USAGEFLEET_ENDPOINT="https://track.example.com"
-export USAGEFLEET_TOKEN="uf_xxx"
-```
-
-Persist it by appending those lines to `~/.bashrc` / `~/.zshrc`, then
-`source ~/.zshrc`. Or set it inline for a single command:
-
-```bash
-USAGEFLEET_ENDPOINT=https://track.example.com USAGEFLEET_TOKEN=uf_xxx usagefleet run
-```
-
-**fish**:
-
-```fish
-set -x USAGEFLEET_ENDPOINT "https://track.example.com"
-set -x USAGEFLEET_TOKEN "uf_xxx"
-# persist (writes to universal vars, survives restarts):
-set -Ux USAGEFLEET_TOKEN "uf_xxx"
-set -Ux USAGEFLEET_ENDPOINT "https://track.example.com"
-```
-
-**PowerShell** (Windows) — current session:
-
-```powershell
-$env:USAGEFLEET_ENDPOINT = "https://track.example.com"
-$env:USAGEFLEET_TOKEN = "uf_xxx"
-# persist for your user (new shells only):
-setx USAGEFLEET_TOKEN "uf_xxx"
-setx USAGEFLEET_ENDPOINT "https://track.example.com"
-```
-
-**cmd.exe** (Windows):
-
-```cmd
-set USAGEFLEET_ENDPOINT=https://track.example.com
-set USAGEFLEET_TOKEN=uf_xxx
-:: persist:  setx USAGEFLEET_TOKEN "uf_xxx"
-```
-
-> Prefer not to put a long-lived token in shell history/rc files? Use
-> `usagefleet install --endpoint <url> --token <t>` instead — it writes
-> `~/.config/usagefleet/config.json` (mode `600`), which the collector reads
-> automatically. The write merges, so re-running it rotates the token without
-> resetting your tail offsets.
-> When run as a service, `usagefleet install` bakes every `USAGEFLEET_*` value
-> that is currently set (plus `ANTHROPIC_API_KEY`) into the launchd/systemd unit.
-> The unit is written mode `600`, since it holds those secrets.
-
-## Run
+## Commands
 
 ```bash
+usagefleet status         # service health, last limits reading, resolved config
 usagefleet run            # one scan: upload usage + report limits
-usagefleet watch          # poll continuously
+usagefleet watch          # poll continuously (what the service runs)
 usagefleet limits         # report ONLY your real 5h/weekly limit usage
 usagefleet guard          # exit 2 if this device's group is over a blocking limit
-usagefleet update         # upgrade to the latest published version now
-usagefleet status         # service health, last limits reading, resolved config
-usagefleet version        # bare release version
+usagefleet notify-test    # fire a sample desktop notification
+usagefleet update         # upgrade now (it also self-updates every 6h)
+usagefleet config         # config file location + every env override
+usagefleet install        # (re)install the background service, idempotent
+usagefleet uninstall      # remove it
 ```
 
-### Updates
-
-`watch` asks the npm registry for the published version at startup and then
-every 6 hours (`USAGEFLEET_UPDATE_INTERVAL`, in seconds); when it differs from
-the one baked into this build it runs `npm install -g @usagefleet/cli@<version>`
-and re-runs `install` to restart the service on it. `usagefleet update` does the
-same on demand.
+## What it collects
 
-npm is called through the absolute path next to the `node` running the
-collector, because a launchd/systemd service gets a minimal PATH that rarely has
-your version manager on it.
+- **Token usage** — Claude Code (`~/.claude/projects/**/*.jsonl`), Claude
+  Desktop agent-mode (Cowork) sessions, and the
+  [pi](https://github.com/badlogic/pi-mono) agent (`~/.pi/agent/sessions`,
+  Anthropic-provider records only; other providers don't touch Claude limits).
+  A per-file byte offset in the config file means each line is sent once;
+  rotation and truncation are handled and partial lines are never sent. Delivery
+  is at-least-once — the server dedups on `uuid`.
+- **Your real limit %** — the collector uses the Claude login already on the
+  machine (subscription OAuth from `claude`: macOS login Keychain, elsewhere
+  `~/.claude/.credentials.json`; falling back to `ANTHROPIC_API_KEY`), sends a
+  1-token ping to the Messages API, and reads Anthropic's
+  `anthropic-ratelimit-unified-5h/7d-utilization` headers. Credentials never
+  leave the machine — only the percentages do. `usagefleet status` shows which
+  login was found.
 
-Every failure is a no-op: registry unreachable, a version string that isn't
-plain semver, npm missing, npm exiting non-zero (a root-owned global prefix is
-the usual cause) and locally-built (`dev`) builds all leave the install as it
-was — the service is only restarted after npm reports success. Set
-`USAGEFLEET_UPDATE=0` to turn the check off.
+Uploaded per record: token counts, model, session id, hostname, working
+directory, git branch. Prompts, responses and file contents are never read.
 
-The collector tracks a per-file byte offset in the config file's `state`
-section, so each line is sent once; it handles rotation/truncation and never
-sends a partial line. Delivery is at-least-once — the server dedups on `uuid`.
+## Desktop notifications
 
-### Real limit % (auto-detected)
+The first time a window crosses a threshold (default `80` and `95`) you get a
+desktop notification — once per threshold per window, re-armed when the window
+resets. macOS uses `osascript`, Linux `notify-send` (falling back to
+`kdialog --passivepopup`; install `libnotify-bin` if neither exists), Windows a
+WinRT toast via `powershell.exe`.
 
-On `run`/`watch`/`limits`, the collector reads your **local Claude login** on
-this machine and reports your true utilization — no keys pasted anywhere:
+`usagefleet notify-test` confirms it works. Tune with
+`USAGEFLEET_NOTIFY_THRESHOLDS="50,80,95"`, disable with `USAGEFLEET_NOTIFY=0`.
 
-1. **Subscription** — the OAuth token from `claude` (Claude Code). On macOS it's
-   read from the login Keychain (`Claude Code-credentials`); on Linux/Windows from
-   `~/.claude/.credentials.json`. Sign in once with `claude` and it's detected.
-2. **API key** — falls back to `ANTHROPIC_API_KEY` if no subscription login.
-
-It sends a 1-token ping to the Messages API and reads Anthropic's
-`anthropic-ratelimit-unified-5h/7d-utilization` (and `-reset`) headers, then POSTs
-the percentages to the server. `usagefleet status` shows which login was found.
-The token/credentials never leave your machine — only the resulting percentages
-are uploaded.
-
-### Blocking prompts over the limit
+## Blocking prompts over the limit
 
 A group can be set to **refuse new prompts** once it has burned its budget slice
-(1/group count of the account limit) for a window. Two switches per group, both
-off by default — flip them in the database:
-
-```sql
-UPDATE groups SET block_on_session_limit = true WHERE name = 'Backend';  -- 5h window
-UPDATE groups SET block_on_weekly_limit  = true WHERE name = 'Backend';  -- 7d window
-```
-
-Enforcement is a Claude Code `UserPromptSubmit` hook, registered in
-`~/.claude/settings.json` automatically by `usagefleet install` (and removed
-by `usagefleet uninstall`). Re-running install refreshes the path instead of
-stacking a second hook; a settings file that doesn't parse is left untouched.
-Set `USAGEFLEET_HOOK=0` to keep your settings file out of it and add the hook
-yourself:
+(1/N of the account limit) for a window — a switch per window on the Groups
+page, both off by default. `usagefleet install` registers a Claude Code `UserPromptSubmit` hook in
+`~/.claude/settings.json` (removed by `uninstall`, refreshed rather than stacked
+on re-install, and skipped entirely with `USAGEFLEET_HOOK=0`):
 
 ```json
 {
@@ -205,79 +91,81 @@ yourself:
 }
 ```
 
-`usagefleet guard` asks the server whether the calling device's group is over
-a window it blocks on; exit code 2 refuses the prompt and shows the reason.
-It **fails open** everywhere else — no config, server down, timeout (5s), old
-server, 429 — because a tracker problem must never stop you from working.
-Only whole prompts are blocked, never tool calls mid-turn, so the current turn
-always finishes.
+`guard` **fails open** everywhere else — no config, server down, timeout (5s),
+old server, 429 — because a tracker problem must never stop you working. Only
+whole prompts are blocked, never tool calls mid-turn, so the current turn always
+finishes.
 
-### Desktop notifications
+## Configuration
 
-When the collector reads your real 5h/weekly utilization, it raises a **desktop
-notification** the first time each window crosses a threshold (default `80%` and
-`95%`). It fires at most once per threshold per window and re-arms when the
-window resets, so it never spams.
+`~/.config/usagefleet/config.json` (honours `XDG_CONFIG_HOME`) holds everything
+the CLI persists: your settings plus two machine-managed sections, `state` (tail
+offsets) and `notify` (which thresholds already fired). Delete it to start
+clean. Re-running `install` merges, so rotating a token doesn't reset offsets.
 
-```bash
-usagefleet notify-test     # fire a sample notification to confirm it works
-```
+Env vars override the file:
+
+| Variable | Meaning |
+|----------|---------|
+| `USAGEFLEET_ENDPOINT` | server base URL (default `https://usagefleet.com`). Must be `https://`, loopback may be `http://` |
+| `USAGEFLEET_TOKEN` | device token |
+| `USAGEFLEET_PROJECTS` | override `~/.claude/projects` |
+| `USAGEFLEET_DESKTOP` | override the Claude Desktop sessions dir; `off` to skip it |
+| `USAGEFLEET_PI` | override the pi sessions dirs, comma-separated; `off` to skip |
+| `USAGEFLEET_INTERVAL` | watch poll seconds (default 15) |
+| `USAGEFLEET_LIMITS_INTERVAL` | seconds between limit pings (default 300, so the 1-token ping isn't every cycle) |
+| `USAGEFLEET_NOTIFY` | desktop notifications, on by default |
+| `USAGEFLEET_NOTIFY_THRESHOLDS` | utilization % that trigger an alert (default `80,95`) |
+| `USAGEFLEET_BATCH` | records per upload (default 100, server caps at 1000) |
+| `USAGEFLEET_CONFIG` | override the config file path |
+| `USAGEFLEET_UPDATE` | `0` turns the self-update check off |
+| `USAGEFLEET_UPDATE_INTERVAL` | seconds between update checks (default `21600` = 6h) |
+| `USAGEFLEET_HOOK` | `0` keeps the prompt-blocking hook out of `~/.claude/settings.json` |
 
-- **macOS** — uses `osascript` → Notification Center (no extra install).
-- **Linux (KDE Plasma / freedesktop)** — uses `notify-send`; if that's missing it
-  falls back to KDE's `kdialog --passivepopup`. Install `notify-send` via
-  `libnotify` (e.g. `apt install libnotify-bin`) if neither is present.
-- **Windows** — a WinRT toast via built-in `powershell.exe` → Action Center (no
-  extra install; it appears under "Windows PowerShell"). Check Settings →
-  Notifications if nothing shows up.
+When run as a service, `install` bakes every `USAGEFLEET_*` value currently set
+(plus `ANTHROPIC_API_KEY`) into the launchd/systemd unit, written mode `600`.
 
-Tune or disable:
+## Background service
 
-```bash
-export USAGEFLEET_NOTIFY_THRESHOLDS="50,80,95"   # alert at 50/80/95%
-export USAGEFLEET_NOTIFY=0                         # turn notifications off
-```
+`install` is idempotent and reload-safe: re-running it rewrites the service
+definition and restarts it, so it doubles as the update step. It launches an
+absolute `node` plus the installed package path, so an empty service PATH is
+fine — but removing that Node version (`nvm uninstall`) stops the collector
+until you re-run `usagefleet install` under the new one.
+
+- **macOS** — a LaunchAgent (`~/Library/LaunchAgents`, RunAtLoad + KeepAlive),
+  booted immediately. Logs in `~/Library/Logs/usagefleet/`. Plist is mode `600`:
+  it holds your token.
+- **Linux** — a `systemd --user` unit, plus `loginctl enable-linger $USER` so it
+  survives logout. If `systemctl` can't be driven it prints the manual steps.
+- **Windows** — a Scheduled Task (`usagefleet`) starting at logon, restarting on
+  failure, running hidden through a `wscript` launcher in
+  `%LOCALAPPDATA%\usagefleet` (which carries the env values set at install
+  time). Log: `%LOCALAPPDATA%\usagefleet\usagefleet.log`. Inspect with
+  `schtasks /query /tn usagefleet /v /fo list`.
+
+> **macOS limits under the service.** Usage collection works headless. Reading
+> the login Keychain for the real limit % may be denied to a non-interactive
+> agent — the collector logs a clear hint. Either approve `/usr/bin/security`
+> access to the `Claude Code-credentials` item once, or set `ANTHROPIC_API_KEY`
+> before `usagefleet install` so limits use the API key.
 
-> **Under a background service.** On macOS the LaunchAgent runs in your GUI
-> session, so notifications appear normally. On Linux a `systemd --user` service
-> needs access to your session bus (`DBUS_SESSION_BUS_ADDRESS`) for `notify-send`
-> to reach the notification daemon — typical for `--user` units in a graphical
-> login. `usagefleet install` bakes `USAGEFLEET_NOTIFY*` into the unit.
+## Updates
 
-## Run as a background service
+`watch` checks the npm registry at startup and every 6 hours; on a new version
+it runs `npm install -g @usagefleet/cli@<version>` and re-runs `install` to
+restart the service on it. `usagefleet update` does the same on demand. npm is
+called through the absolute path next to the running `node`, because a
+launchd/systemd service gets a minimal PATH.
+
+Every failure is a no-op — registry unreachable, non-semver version, npm
+missing or exiting non-zero, local `dev` builds — and the service is only
+restarted after npm reports success.
+
+## From source
 
 ```bash
-usagefleet install        # launchd (macOS) / systemd --user (Linux) / Task Scheduler (Windows)
-usagefleet uninstall
+cd apps/cli
+bun install
+bun run src/index.ts status   # or: npm run build && node dist/index.js status
 ```
-
-`install` is idempotent and reload-safe: re-running it rewrites the service
-definition and restarts it, so it doubles as the update step. The service is
-launched as an absolute `node` plus the installed package path, so an empty
-service PATH is fine — but removing that Node version (`nvm uninstall`) stops
-the collector until you re-run `usagefleet install` under the new one.
-
-- **macOS** — installs a LaunchAgent (`~/Library/LaunchAgents`, RunAtLoad +
-  KeepAlive) and boots it (bootout → bootstrap → kickstart). Logs at
-  `~/Library/Logs/usagefleet/usagefleet.*.log` (not `/tmp`, which is
-  world-writable). The plist is written mode `600`: it holds your token.
-- **Linux** — writes a `--user` unit and runs `systemctl --user daemon-reload`,
-  `enable --now`, `restart`, plus `loginctl enable-linger $USER` automatically so
-  it survives logout. If `systemctl` can't be driven, it prints the manual steps.
-- **Windows** — registers a Scheduled Task (`usagefleet`) that starts at logon,
-  restarts on failure, and runs **hidden** (no console window) through a
-  generated `wscript` launcher in `%LOCALAPPDATA%\usagefleet`. Task XML has no
-  env support, so the launcher carries the `USAGEFLEET_*` values that were set
-  when you ran `install`, and redirects output to
-  `%LOCALAPPDATA%\usagefleet\usagefleet.log` (truncated on each start).
-  Inspect it with `schtasks /query /tn usagefleet /v /fo list`.
-
-The OS is reported automatically (`process.platform` → `mac`/`linux`/`windows`).
-
-> **macOS limits under the service.** Usage collection (reading JSONL files) works
-> headless. The **real limit %** feature reads the login Keychain, and a
-> non-interactive launchd agent may be denied that read — the collector logs a
-> clear hint when this happens. If it does, either approve `/usr/bin/security`
-> access to the `Claude Code-credentials` item once, or set `ANTHROPIC_API_KEY`
-> before `usagefleet install` (it's baked into the service) so limits use the
-> API key instead.

package/dist/collector.js

@@ -102,7 +102,7 @@ export async function runOnce(cfg, log = () => {
         else if (outcome === 'plan') {
             // The device sits outside the account's device limit (402). Every other
             // file gets the same answer, so stop and say what unblocks it once.
-            log('warn', `device outside your plan's device limit · free a slot or upgrade at ${cfg.endpoint}/devices · nothing is lost, uploads resume once it fits`);
+            log('warn', planWall(cfg.endpoint));
             result.failed = true;
             break;
         }
@@ -205,6 +205,11 @@ function pruneMissingFiles(state, scanned) {
     }
     return removed;
 }
+/** The one thing that unblocks a device parked outside the account's device limit.
+ *  Shared by both upload legs so the wording cannot drift between them. */
+function planWall(endpoint) {
+    return `device outside your plan's device limit · free a slot or upgrade at ${endpoint}/devices · nothing is lost, uploads resume once it fits`;
+}
 /**
  * Auto-detect the local Claude login, read the real 5h/weekly utilization from
  * Anthropic's rate-limit headers, and report it to the server. Best-effort —
@@ -235,9 +240,21 @@ export async function reportLimitsOnce(cfg, log = () => {
         log('warn', `limits fetch failed · ${error.message}`);
         return null;
     }
-    const ok = await postLimits(report, cfg);
-    if (!ok) {
-        log('warn', 'limits upload failed');
+    // Same vocabulary as the usage leg: a rejection the operator can act on has to
+    // say which one it is, since this runs every cycle and an anonymous failure
+    // would repeat forever without ever naming the fix.
+    const outcome = await postLimits(report, cfg);
+    if (outcome === 'plan') {
+        log('warn', planWall(cfg.endpoint));
+    }
+    else if (outcome === 'auth') {
+        log('warn', 'limits rejected · device token invalid or revoked · re-run `usagefleet install --token <device-token>`');
+    }
+    else if (outcome === 'invalid') {
+        log('warn', 'limits rejected as malformed · this is a bug, please report it');
+    }
+    else if (outcome !== 'ok') {
+        log('warn', 'limits upload failed · retrying next cycle');
     }
     // Cache the reading so `status` can show current usage without spending
     // another billable API call.

package/dist/config.js

@@ -17,7 +17,7 @@ export function loadConfig() {
         throw new Error('USAGEFLEET_TOKEN is not set');
     }
     if (!isSecureEndpoint(endpoint)) {
-        throw new Error(`USAGEFLEET_ENDPOINT must be https (got ${endpoint}). It carries the device token on every request and self-update executes a binary fetched from it.`);
+        throw new Error(`endpoint must be https (got ${endpoint}). It carries the device token on every request. Set --endpoint or USAGEFLEET_ENDPOINT.`);
     }
     // Guard batch size: "0" (infinite loop), NaN (silent drop), fractional → 100.
     // Clamped to the server's own 1000-record cap, since a larger batch is

package/dist/index.js

@@ -8,7 +8,7 @@ import { sendNotification } from './notify.js';
 import { detectOs } from './os.js';
 import { RELEASE_VERSION } from './release.js';
 import { serviceStatus } from './service.js';
-import { readStore, storePath, updateStore } from './store.js';
+import { readStore, storePath } from './store.js';
 import { ago, bar, blue, dim, fail, green, header, hint, host, line, note, pct, row, state as stateLine, step, tilde, warn, yellow, } from './ui.js';
 import { checkForUpdate } from './update.js';
 function flag(name) {
@@ -194,23 +194,61 @@ function limitHealth(fiveHour, sevenDay) {
  *  token without resetting tail offsets. Endpoint only matters when
  *  self-hosting; unset keeps whatever is configured. */
 async function cmdInstall() {
+    // Apply the flags to the env loadConfig() reads rather than writing them to the
+    // store, so there is exactly one precedence chain and install() persists its
+    // single winner. Writing to the store first inverted the precedence: loadConfig
+    // prefers the env, so a stale USAGEFLEET_TOKEN in the install shell beat the
+    // flag and got written back over it, silently voiding token rotation. It also
+    // means a rejected value never reaches disk.
     const endpoint = flag('endpoint');
     const token = flag('token');
-    if (endpoint || token) {
-        updateStore(storePath(), store => {
-            if (endpoint) {
-                store.endpoint = endpoint;
-            }
-            if (token) {
-                store.token = token;
-            }
-        });
+    if (endpoint) {
+        process.env.USAGEFLEET_ENDPOINT = endpoint;
+    }
+    if (token) {
+        process.env.USAGEFLEET_TOKEN = token;
     }
     const { install } = await import('./service.js');
     install();
 }
-/** Command list and env reference, in the same padded-column style as the
- *  result lines: name in white, meaning in gray. */
+/** Padded two-column list — name in white, meaning in gray, like the result
+ *  lines. Shared by `help` and `config`. */
+function print(rows) {
+    const width = Math.max(...rows.map(([name]) => name.length));
+    for (const [name, meaning] of rows) {
+        console.log(`  ${name.padEnd(width)}  ${dim(meaning)}`);
+    }
+}
+/** Where settings live and every env var that overrides them. Reads nothing:
+ *  it must work before a token exists, when the config is what you're fixing. */
+function cmdConfig() {
+    const env = [
+        ['USAGEFLEET_ENDPOINT', 'server base URL (self-hosting only)'],
+        ['USAGEFLEET_TOKEN', 'device token from the Devices page'],
+        ['USAGEFLEET_PROJECTS', 'override ~/.claude/projects'],
+        ['USAGEFLEET_DESKTOP', 'override the Claude Desktop dir ("off" disables)'],
+        ['USAGEFLEET_PI', 'override pi session dirs, comma-separated'],
+        ['USAGEFLEET_INTERVAL', 'watch interval seconds (default 15)'],
+        ['USAGEFLEET_LIMITS_INTERVAL', 'seconds between limits pings (default 300)'],
+        ['USAGEFLEET_BATCH', 'records per upload (default 100, max 1000)'],
+        ['USAGEFLEET_NOTIFY', 'desktop notifications (0 disables)'],
+        ['USAGEFLEET_NOTIFY_THRESHOLDS', 'comma list of % alerts (default 80,95)'],
+        ['USAGEFLEET_HOOK', 'register the guard on install (0 skips)'],
+        ['USAGEFLEET_UPDATE', 'self-update while watching (0 disables)'],
+        ['USAGEFLEET_UPDATE_INTERVAL', 'seconds between update checks (default 21600)'],
+        ['USAGEFLEET_CONFIG', 'relocate the config file'],
+    ];
+    console.log(header());
+    console.log(hint('settings, tail offsets and notification marks'));
+    console.log('');
+    console.log(row('file', tilde(storePath())));
+    console.log('');
+    console.log(hint('env — overrides the file'));
+    print(env);
+    console.log('');
+    console.log(hint('`usagefleet status` shows the resolved values'));
+}
+/** Command list, in the same padded-column style as the result lines. */
 function help() {
     const commands = [
         ['run', 'scan once, upload usage + report limits'],
@@ -220,39 +258,16 @@ function help() {
         ['update', 'update to the latest release now'],
         ['notify-test', 'fire a test desktop notification'],
         ['status', 'service health, limits, resolved config'],
+        ['config', 'config file location and env overrides'],
         ['version', 'print the release version'],
         ['install --token <t>', 'configure + install the service and prompt guard'],
         ['uninstall', 'remove the service and the guard'],
     ];
-    const env = [
-        ['USAGEFLEET_ENDPOINT', 'server base URL (self-hosting only)'],
-        ['USAGEFLEET_TOKEN', 'device token from the Devices page'],
-        ['USAGEFLEET_PROJECTS', 'override ~/.claude/projects'],
-        ['USAGEFLEET_DESKTOP', 'override the Claude Desktop dir ("off" disables)'],
-        ['USAGEFLEET_PI', 'override pi session dirs, comma-separated'],
-        ['USAGEFLEET_INTERVAL', 'watch interval seconds'],
-        ['USAGEFLEET_NOTIFY', 'desktop notifications (0 disables)'],
-        ['USAGEFLEET_HOOK', 'register the guard on install (0 skips)'],
-        ['USAGEFLEET_UPDATE', 'self-update while watching (0 disables)'],
-        ['USAGEFLEET_UPDATE_INTERVAL', 'seconds between update checks (default 21600)'],
-        ['USAGEFLEET_NOTIFY_THRESHOLDS', 'comma list of % alerts (default 80,95)'],
-        ['USAGEFLEET_CONFIG', 'relocate the config file'],
-    ];
-    const pad = (rows) => Math.max(...rows.map(([name]) => name.length));
-    const print = (rows) => {
-        const width = pad(rows);
-        for (const [name, meaning] of rows) {
-            console.log(`  ${name.padEnd(width)}  ${dim(meaning)}`);
-        }
-    };
     console.log(header());
-    console.log(hint('claude usage collector'));
     console.log('');
     print(commands);
     console.log('');
-    console.log(hint('env — overrides ~/.config/usagefleet/config.json, which holds'));
-    console.log(hint('settings, tail offsets and notification marks'));
-    print(env);
+    console.log(hint('`usagefleet config` lists the config file and its env overrides'));
 }
 async function main() {
     // Log-and-continue for the long-running watch daemon: a stray rejection must
@@ -291,6 +306,9 @@ async function main() {
         case 'status': {
             return cmdStatus();
         }
+        case 'config': {
+            return cmdConfig();
+        }
         // Bare version, so the installer can compare builds without parsing help.
         case 'version':
         case '--version':

package/dist/release.js

@@ -1,2 +1,2 @@
 // Generated by .github/workflows/release.yml.
-export const RELEASE_VERSION = "1.2.69";
+export const RELEASE_VERSION = "1.2.71";