@usagefleet/cli 1.2.97 → 1.2.99

package/README.md

@@ -126,24 +126,25 @@ 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 `login` merges, so rotating a token doesn't reset offsets.
 
-Env vars override the file:
-
-| Variable | Meaning |
-|----------|---------|
-| `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 reports (default 60; 300 on API keys, where each report costs a 1-token ping) |
-| `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 guard out of Claude Code and pi |
-| `CLAUDE_CONFIG_DIR` | Claude Code's own knob: which login to watch (default `~/.claude`) |
+Every knob is a top-level key in that file, and the matching env var overrides
+it (`usagefleet config` prints this same table):
+
+| File key | Env override | Meaning |
+|----------|--------------|---------|
+| `token` | `USAGEFLEET_TOKEN` | device token |
+| `projectsDir` | `USAGEFLEET_PROJECTS` | override `~/.claude/projects` |
+| `desktopDir` | `USAGEFLEET_DESKTOP` | override the Claude Desktop sessions dir; `off` to skip it |
+| `piDir` | `USAGEFLEET_PI` | pi sessions dirs — string or array in the file, comma-separated in env; `off` to skip |
+| `interval` | `USAGEFLEET_INTERVAL` | watch poll seconds (default 15) |
+| `limitsInterval` | `USAGEFLEET_LIMITS_INTERVAL` | seconds between limit reports (default 60; 300 on API keys, where each report costs a 1-token ping) |
+| `notifications` | `USAGEFLEET_NOTIFY` | desktop notifications, on by default (`false`/`0` disables) |
+| `notifyThresholds` | `USAGEFLEET_NOTIFY_THRESHOLDS` | utilization % that trigger an alert — array in the file, comma list in env (default `80,95`) |
+| `batch` | `USAGEFLEET_BATCH` | records per upload (default 100, server caps at 1000) |
+| `update` | `USAGEFLEET_UPDATE` | `false`/`0` turns the self-update check off |
+| `updateInterval` | `USAGEFLEET_UPDATE_INTERVAL` | seconds between update checks (default `21600` = 6h) |
+| `hook` | `USAGEFLEET_HOOK` | `false`/`0` keeps the prompt-blocking guard out of Claude Code and pi |
+| — | `USAGEFLEET_CONFIG` | override the config file path (env only — it locates the file) |
+| — | `CLAUDE_CONFIG_DIR` | Claude Code's own knob: which login to watch (default `~/.claude`) |
 
 When run as a service, `login` bakes every `USAGEFLEET_*` value currently set
 (plus `ANTHROPIC_API_KEY` and `CLAUDE_CONFIG_DIR`) into the launchd/systemd

package/dist/config.js

@@ -18,7 +18,7 @@ export function loadConfig() {
     // 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
     // rejected as malformed and would cost the whole chunk a bisect to discover.
-    const parsedBatch = Math.floor(Number(process.env.USAGEFLEET_BATCH));
+    const parsedBatch = Math.floor(positiveNumber(process.env.USAGEFLEET_BATCH, file.batch) ?? 100);
     const batchSize = Number.isFinite(parsedBatch) && parsedBatch > 0 ? Math.min(parsedBatch, MAX_BATCH) : 100;
     return {
         batchSize,
@@ -29,6 +29,27 @@ export function loadConfig() {
         token,
     };
 }
+/** env → file → nothing, for the numeric knobs (intervals, batch): an env
+ *  value wins when present (empty string counts as unset, same `||` rule as
+ *  loadConfig), and a non-positive or non-numeric candidate is skipped rather
+ *  than trusted. */
+export function positiveNumber(env, fromFile) {
+    for (const candidate of [env ? Number(env) : null, fromFile]) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** The off-switches (hook, update, notifications): an env value wins when
+ *  present — 0/false/off/no disable, anything else enables — otherwise `false`
+ *  under the config-file key disables. */
+export function flagOff(env, fromFile) {
+    if (env) {
+        return /^(0|false|off|no)$/i.test(env.trim());
+    }
+    return fromFile === false;
+}
 /** pi scan roots: env "off"/"0" disables, else a comma-separated env list, else
  *  the config file's string-or-array, else every auto-detected default. */
 export function resolvePiDirs(env, fromFile) {

package/dist/hook.js

@@ -1,7 +1,9 @@
 import { mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { writeFileAtomic } from './atomic-write.js';
+import { flagOff } from './config.js';
 import { claudeSettingsPath } from './paths.js';
+import { readStore } from './store.js';
 import { step, tilde, warn } from './ui.js';
 /** Outer bound on the hook, in seconds. runGuard's own fetch gives up after 5s
  *  and fails open; this only matters if the process itself wedges. */
@@ -102,11 +104,11 @@ function editSettings(transform, onWrite) {
 /**
  * Register `usagefleet guard` as a Claude Code UserPromptSubmit hook, so a
  * group with blocking enabled actually refuses prompts. Called by
- * `usagefleet login`; set USAGEFLEET_HOOK=0 to keep settings.json
- * untouched.
+ * `usagefleet login`; USAGEFLEET_HOOK=0 or `"hook": false` in the config file
+ * keeps settings.json untouched.
  */
 export function installPromptHook(program) {
-    if (process.env.USAGEFLEET_HOOK === '0') {
+    if (flagOff(process.env.USAGEFLEET_HOOK, readStore().hook)) {
         return;
     }
     const command = guardCommand(program, process.env.USAGEFLEET_CONFIG);

package/dist/index.js

@@ -2,7 +2,7 @@
 import { detectClaudeCreds } from './claude-creds.js';
 import { reportLimitsOnce, runOnce } from './collector.js';
 import { commands, completionScript, installCompletions, removeCompletions, shells, suggest } from './completion.js';
-import { ENDPOINT, loadConfig } from './config.js';
+import { ENDPOINT, loadConfig, positiveNumber } from './config.js';
 import { runGuard } from './guard.js';
 import { loadNotifyConfig } from './notifier.js';
 import { sendNotification } from './notify.js';
@@ -68,22 +68,25 @@ async function cmdLimits() {
 }
 async function cmdWatch() {
     const cfg = loadConfig();
-    const raw = Number(flag('interval') ?? process.env.USAGEFLEET_INTERVAL ?? 15);
+    const settings = readStore(cfg.storePath);
+    const raw = flag('interval') == null
+        ? (positiveNumber(process.env.USAGEFLEET_INTERVAL, settings.interval) ?? 15)
+        : Number(flag('interval'));
     const interval = Math.max(1, Number.isFinite(raw) && raw > 0 ? raw : 15) * 1000;
     // Limits reporting is decoupled from the much faster usage poll. Default
     // interval depends on how the reading is fetched: subscription logins use the
     // free oauth/usage endpoint (60s keeps the dashboard split fresh at zero token
     // cost), API keys pay a 1-token Messages ping per reading (300s). An explicit
-    // USAGEFLEET_LIMITS_INTERVAL overrides both.
-    const rawLimits = Number(process.env.USAGEFLEET_LIMITS_INTERVAL);
-    const explicitLimits = Number.isFinite(rawLimits) && rawLimits > 0 ? rawLimits * 1000 : null;
+    // USAGEFLEET_LIMITS_INTERVAL or `limitsInterval` file key overrides both.
+    const rawLimits = positiveNumber(process.env.USAGEFLEET_LIMITS_INTERVAL, settings.limitsInterval);
+    const explicitLimits = rawLimits ? rawLimits * 1000 : null;
     let limitsInterval = explicitLimits ?? 60_000;
     let lastLimitsAt = 0;
     // Self-update: once at startup, then every USAGEFLEET_UPDATE_INTERVAL seconds
     // (default 6h — a release lands on a device the same day, not the next).
-    // USAGEFLEET_UPDATE=0 opts out.
-    const rawUpdate = Number(process.env.USAGEFLEET_UPDATE_INTERVAL ?? 6 * 60 * 60);
-    const updateInterval = Math.max(60, Number.isFinite(rawUpdate) && rawUpdate > 0 ? rawUpdate : 6 * 60 * 60) * 1000;
+    // USAGEFLEET_UPDATE=0 or `"update": false` opts out.
+    const rawUpdate = positiveNumber(process.env.USAGEFLEET_UPDATE_INTERVAL, settings.updateInterval) ?? 6 * 60 * 60;
+    const updateInterval = Math.max(60, rawUpdate) * 1000;
     let lastUpdateAt = 0;
     const watching = [cfg.projectsDir, cfg.desktopDir, ...cfg.piDirs].filter((d) => !!d);
     console.log(header(`watching every ${interval / 1000}s`));
@@ -154,7 +157,7 @@ async function cmdWatch() {
 function cmdNotifyTest() {
     const cfg = loadNotifyConfig();
     if (!cfg.enabled) {
-        console.log(warn('notify', 'disabled · unset USAGEFLEET_NOTIFY=0 to enable'));
+        console.log(warn('notify', 'disabled · unset USAGEFLEET_NOTIFY=0 / `"notifications": false` to enable'));
         return;
     }
     sendNotification('usagefleet', 'Test notification — desktop alerts are working.', {
@@ -245,31 +248,40 @@ function print(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. */
+/** Where settings live: every knob is a key in the config file, and the
+ *  matching env var overrides it. Reads nothing: it must work before a token
+ *  exists, when the config is what you're fixing. */
 function cmdConfig() {
-    const env = [
-        ['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 reports (default 60; 300 on API keys)'],
-        ['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'],
+    const knobs = [
+        ['token', 'USAGEFLEET_TOKEN', 'device token from the Devices page'],
+        ['projectsDir', 'USAGEFLEET_PROJECTS', 'override ~/.claude/projects'],
+        ['desktopDir', 'USAGEFLEET_DESKTOP', 'override the Claude Desktop dir ("off" disables)'],
+        ['piDir', 'USAGEFLEET_PI', 'pi session dirs · string or array; env comma-separated'],
+        ['interval', 'USAGEFLEET_INTERVAL', 'watch interval seconds (default 15)'],
+        [
+            'limitsInterval',
+            'USAGEFLEET_LIMITS_INTERVAL',
+            'seconds between limits reports (default 60; 300 on API keys)',
+        ],
+        ['batch', 'USAGEFLEET_BATCH', 'records per upload (default 100, max 1000)'],
+        ['notifications', 'USAGEFLEET_NOTIFY', 'desktop notifications (false/0 disables)'],
+        ['notifyThresholds', 'USAGEFLEET_NOTIFY_THRESHOLDS', '% alerts · array; env comma list (default 80,95)'],
+        ['hook', 'USAGEFLEET_HOOK', 'register the prompt guard on install (false/0 skips)'],
+        ['update', 'USAGEFLEET_UPDATE', 'self-update while watching (false/0 disables)'],
+        ['updateInterval', 'USAGEFLEET_UPDATE_INTERVAL', 'seconds between update checks (default 21600)'],
+        ['—', 'USAGEFLEET_CONFIG', 'relocate the config file (env only — it locates the 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(hint('file key · env override wins'));
+    const keyWidth = Math.max(...knobs.map(([key]) => key.length));
+    const envWidth = Math.max(...knobs.map(([, env]) => env.length));
+    for (const [key, env, meaning] of knobs) {
+        console.log(`  ${key.padEnd(keyWidth)}  ${env.padEnd(envWidth)}  ${dim(meaning)}`);
+    }
     console.log('');
     console.log(hint('`usagefleet status` shows the resolved values'));
 }

package/dist/notifier.js

@@ -1,23 +1,17 @@
+import { flagOff } from './config.js';
 import { sendNotification } from './notify.js';
 import { readStore, storePath, updateStore } from './store.js';
 const DEFAULT_THRESHOLDS = [80, 95];
-/** Resolve notify config from env. Enabled by default; disable with
- *  USAGEFLEET_NOTIFY=0 (also: false/off/no). Thresholds from
- *  USAGEFLEET_NOTIFY_THRESHOLDS as a comma list (e.g. "50,80,95"). */
-export function loadNotifyConfig(env = process.env) {
-    const flag = env.USAGEFLEET_NOTIFY;
-    const enabled = flag == null || !/^(0|false|off|no)$/i.test(flag.trim());
-    let thresholds = DEFAULT_THRESHOLDS;
+/** Resolve notify config, env first then the config file. Enabled by default;
+ *  disable with USAGEFLEET_NOTIFY=0 (also: false/off/no) or `"notifications":
+ *  false`. Thresholds from USAGEFLEET_NOTIFY_THRESHOLDS as a comma list
+ *  (e.g. "50,80,95") or a `notifyThresholds` array. */
+export function loadNotifyConfig(env = process.env, file = readStore()) {
+    const enabled = !flagOff(env.USAGEFLEET_NOTIFY, file.notifications);
     const raw = env.USAGEFLEET_NOTIFY_THRESHOLDS;
-    if (raw && raw.trim()) {
-        const parsed = raw
-            .split(',')
-            .map(s => Math.round(Number(s.trim())))
-            .filter(n => Number.isFinite(n) && n > 0 && n <= 100);
-        if (parsed.length > 0) {
-            thresholds = [...new Set(parsed)].toSorted((a, b) => a - b);
-        }
-    }
+    const candidates = raw?.trim() ? raw.split(',').map(s => Number(s.trim())) : (file.notifyThresholds ?? []);
+    const parsed = candidates.map(Math.round).filter(n => Number.isFinite(n) && n > 0 && n <= 100);
+    const thresholds = parsed.length > 0 ? [...new Set(parsed)].toSorted((a, b) => a - b) : DEFAULT_THRESHOLDS;
     return { enabled, thresholds };
 }
 /**

package/dist/pi-hook.js

@@ -1,13 +1,16 @@
 import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { writeFileAtomic } from './atomic-write.js';
+import { flagOff } from './config.js';
 import { piAgentDir } from './paths.js';
+import { readStore } from './store.js';
 import { step, tilde } from './ui.js';
 /** pi has no settings-file hooks; its extension point is a TypeScript file
  *  auto-discovered from `<agent-dir>/extensions/*.ts`. So the pi guard is a
  *  generated file rather than a settings entry, with the same lifecycle as the
  *  Claude hook: written by `login` (which self-update re-runs, refreshing the
- *  baked binary path), removed by `uninstall`, skipped by USAGEFLEET_HOOK=0. */
+ *  baked binary path), removed by `uninstall`, skipped by USAGEFLEET_HOOK=0 or
+ *  `"hook": false` in the config file. */
 const FILE = 'usagefleet-guard.ts';
 export function piGuardPath(agentDir = piAgentDir()) {
     return join(agentDir, 'extensions', FILE);
@@ -70,7 +73,7 @@ export default function (pi: { on(event: 'input', handler: InputHandler): void }
 /** Skips machines without pi (agent dir absent) rather than conjuring a `.pi`
  *  tree that pi itself never made. */
 export function installPiGuard(program, agentDir = piAgentDir()) {
-    if (process.env.USAGEFLEET_HOOK === '0' || !existsSync(agentDir)) {
+    if (flagOff(process.env.USAGEFLEET_HOOK, readStore().hook) || !existsSync(agentDir)) {
         return;
     }
     const path = piGuardPath(agentDir);

package/dist/release.js

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

package/dist/store.js

@@ -41,15 +41,24 @@ function readJson(path) {
 export function freshWindow() {
     return { lastBucket: 0, resetsAt: null };
 }
-/** Fill in every field so callers get a total value, whatever the file held. */
+/** Fill in every field so callers get a total value, whatever the file held.
+ *  Listing fields explicitly (rather than spreading `raw`) is what drops junk
+ *  keys — so every new settings key must be carried through here or the next
+ *  `updateStore` silently erases it. */
 function normalize(raw) {
     return {
+        batch: raw.batch,
         desktopDir: raw.desktopDir,
+        hook: raw.hook,
+        interval: raw.interval,
         limits: raw.limits,
+        limitsInterval: raw.limitsInterval,
+        notifications: raw.notifications,
         notify: {
             fiveHour: { ...freshWindow(), ...raw.notify?.fiveHour },
             sevenDay: { ...freshWindow(), ...raw.notify?.sevenDay },
         },
+        notifyThresholds: raw.notifyThresholds,
         piDir: raw.piDir,
         projectsDir: raw.projectsDir,
         state: {
@@ -58,6 +67,8 @@ function normalize(raw) {
             updatedAt: raw.state?.updatedAt ?? new Date().toISOString(),
         },
         token: raw.token,
+        update: raw.update,
+        updateInterval: raw.updateInterval,
         version: 1,
     };
 }

package/dist/update.js

@@ -1,7 +1,9 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, delimiter, dirname, join } from 'node:path';
+import { flagOff } from './config.js';
 import { RELEASE_VERSION } from './release.js';
+import { readStore } from './store.js';
 import { tilde } from './ui.js';
 /** The published package: one artifact for every OS, installed with
  *  `npm i -g @usagefleet/cli`. */
@@ -157,7 +159,7 @@ export async function checkForUpdate(log, force = false) {
     if (!self) {
         return null;
     }
-    if (!force && process.env.USAGEFLEET_UPDATE === '0') {
+    if (!force && flagOff(process.env.USAGEFLEET_UPDATE, readStore().update)) {
         return null;
     }
     // A rejected fetch (offline, DNS, timeout) must stay inside this function:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@usagefleet/cli",
-	"version": "1.2.97",
+	"version": "1.2.99",
 	"description": "Tails Claude Code, Claude Desktop, and pi agent JSONL logs and reports token usage to a UsageFleet server.",
 	"keywords": [
 		"claude",