@usagefleet/cli 1.2.59 → 1.2.70

package/README.md

@@ -9,14 +9,13 @@ UsageFleet server. Read-only on the log files. Zero runtime dependencies
 
 ## Install
 
-Three commands, identical on macOS, Linux and Windows. You only need a device
+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`):
 
 ```bash
 npm i -g @usagefleet/cli
-usagefleet init --token uf_xxx      # add --endpoint <url> when self-hosting
-usagefleet install                  # autostart at login
+usagefleet install --token uf_xxx   # autostart at login; --endpoint <url> when self-hosting
 ```
 
 In PowerShell chain them with `;` instead of `&&` — Windows PowerShell 5.1 has
@@ -44,7 +43,7 @@ bun run src/index.ts status   # or: npm run build && node dist/index.js status
 Get a device **token** from the server's Devices page, then either:
 
 ```bash
-usagefleet init --endpoint https://track.example.com --token uf_xxx
+usagefleet install --endpoint https://track.example.com --token uf_xxx
 # writes ~/.config/usagefleet/config.json
 ```
 
@@ -120,9 +119,9 @@ set USAGEFLEET_TOKEN=uf_xxx
 ```
 
 > Prefer not to put a long-lived token in shell history/rc files? Use
-> `usagefleet init --endpoint <url> --token <t>` instead — it writes
+> `usagefleet install --endpoint <url> --token <t>` instead — it writes
 > `~/.config/usagefleet/config.json` (mode `600`), which the collector reads
-> automatically. `init` merges, so re-running it rotates the token without
+> 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.
@@ -137,6 +136,7 @@ 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 config         # config file location + every env override
 usagefleet version        # bare release version
 ```
 

package/dist/claude-creds.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import { writeFileAtomic } from './atomic-write.js';
+import { dim, line, yellow } from './ui.js';
 const KEYCHAIN_SERVICE = 'Claude Code-credentials';
 function credentialsFilePath() {
     return join(homedir(), '.claude', '.credentials.json');
@@ -112,8 +113,7 @@ async function refreshOauth(blob, from) {
         // The refresh already rotated the token server-side, so the stored one is
         // now dead: keep using the new one in memory (valid for hours) and make the
         // failure loud — on restart the user will have to `claude login` again.
-        console.error(`could not save the refreshed Claude token (${error.message}) — ` +
-            'run `claude login` if limits stop reporting after a restart');
+        line(yellow('!'), `could not save the refreshed claude token ${dim(`· ${error.message} · run \`claude login\` if limits stop reporting after a restart`)}`);
     }
     return {
         source: 'sub',

package/dist/collector.js

@@ -9,6 +9,7 @@ import { RELEASE_VERSION } from './release.js';
 import { listJsonlFiles } from './scanner.js';
 import { readStore, updateStore } from './store.js';
 import { tailFile } from './tailer.js';
+import { tilde } from './ui.js';
 import { postLimits, uploadBatch } from './uploader.js';
 /** Only files inside a `.../.claude/projects/...` subtree are real usage logs.
  *  Desktop session roots also hold `audit.jsonl` (a full duplicate of the same
@@ -56,6 +57,9 @@ export async function runOnce(cfg, log = () => {
     // Defensive: a bad batchSize must never stall the chunk loop.
     const step = cfg.batchSize > 0 ? Math.floor(cfg.batchSize) : 100;
     let advanced = false;
+    // A server that is down or unreachable fails every file for the same reason,
+    // so the cycle reports one count instead of a screenful of identical lines.
+    let transientFiles = 0;
     for (const { fp, source } of files) {
         let tail;
         try {
@@ -63,7 +67,7 @@ export async function runOnce(cfg, log = () => {
         }
         catch (error) {
             // One unreadable/oversized file must not abort the whole cycle.
-            log(`skip ${fp}: ${error.message}`);
+            log('warn', `skipped ${tilde(fp)} · ${error.message}`);
             continue;
         }
         if (!tail || tail.consumedBytes === 0) {
@@ -75,7 +79,7 @@ export async function runOnce(cfg, log = () => {
             advanced = true;
             continue;
         }
-        // sendChunk absorbs "invalid" by bisecting, so only auth/transient escape.
+        // sendChunk absorbs "invalid" by bisecting, so only auth/plan/transient escape.
         let outcome = 'ok';
         for (let i = 0; i < tail.records.length; i += step) {
             outcome = await sendChunk(tail.records.slice(i, i + step), cfg, result, log);
@@ -91,27 +95,37 @@ export async function runOnce(cfg, log = () => {
             // Token revoked/expired. The data is valid and must NOT be skipped — keep
             // the offset so it uploads once a fresh token is configured. Retrying the
             // remaining files would 401 identically, so stop this cycle and surface.
-            log(`auth rejected (401/403) — device token invalid or revoked; re-run \`usagefleet init\` with a fresh token, then restart the service`);
+            log('warn', 'auth rejected · device token invalid or revoked · re-run `usagefleet install --token <t>` with a fresh token');
+            result.failed = true;
+            break;
+        }
+        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', planWall(cfg.endpoint));
             result.failed = true;
             break;
         }
         else if (outcome === 'invalid') {
             // The whole batch was rejected, not individual records (see sendChunk).
             // Keep the offset: this needs a collector or server fix, not a purge.
-            log(`upload for ${fp} rejected as a whole batch — keeping the offset; check that this collector version and OS are supported by the server`);
+            log('warn', `batch rejected for ${tilde(fp)} · offset kept · check this collector version and OS are supported by the server`);
             result.failed = true;
         }
         else {
-            // transient (402 outside plan, 5xx, network, timeout): keep the offset and
-            // retry next cycle, but DO NOT break — later files must still get a turn.
-            log(`upload failed for ${fp} (transient) — will retry next cycle`);
+            // transient (5xx, network, timeout): keep the offset and retry next cycle,
+            // but DO NOT break — later files must still get a turn.
+            transientFiles += 1;
             result.failed = true;
         }
     }
+    if (transientFiles > 0) {
+        log('warn', `upload failed for ${transientFiles} file${transientFiles === 1 ? '' : 's'} · retrying next cycle`);
+    }
     // One durable write per cycle rather than one per file: the store is fsynced
     // on every save, and a crash mid-cycle only costs a re-upload the server
     // dedups. Only our own section is replaced, so a token written by a
-    // concurrent `usagefleet init` survives.
+    // concurrent `usagefleet install` survives.
     if (pruneMissingFiles(state, files) || advanced) {
         updateStore(cfg.storePath, store => {
             store.state.files = state.files;
@@ -158,11 +172,11 @@ async function sendChunk(records, cfg, result, log, dropCeiling = result.dropped
             // Give up on the record theory. The caller keeps the offset, so the
             // records counted on the way down are retried, not lost — untally them
             // rather than report a loss that did not happen.
-            log(`every split of this batch was rejected, so the batch itself is bad, not its records — nothing skipped`);
+            log('warn', 'every split was rejected · the batch is bad, not its records · nothing skipped');
             result.dropped = dropCeiling - MAX_DROPPED_PER_CHUNK;
             return 'invalid';
         }
-        log(`server rejected record ${single.uuid} as malformed — skipping it`);
+        log('warn', `record ${single.uuid} rejected as malformed · skipped`);
         result.dropped += 1;
         result.failed = true;
         return 'ok';
@@ -191,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 —
@@ -204,12 +223,11 @@ export async function reportLimitsOnce(cfg, log = () => {
         if (process.platform === 'darwin' && macKeychainDenied()) {
             // "Works by hand, broken as a service" signature: a launchd agent can be
             // denied the login-Keychain read. Make it diagnosable instead of silent.
-            log("limits skipped: login Keychain read for 'Claude Code-credentials' was denied " +
-                '(typical under a background launchd agent). Grant /usr/bin/security access to the ' +
-                'item, or set ANTHROPIC_API_KEY for the service.');
+            log('warn', "limits skipped · keychain read for 'Claude Code-credentials' denied, typical under a launchd agent · " +
+                'grant /usr/bin/security access to the item, or set ANTHROPIC_API_KEY for the service');
         }
         else {
-            log('no usable Claude login — missing, or expired with a refresh that failed; ' +
+            log('warn', 'no usable claude login · missing, or expired with a failed refresh · ' +
                 'sign in with `claude` or set ANTHROPIC_API_KEY');
         }
         return null;
@@ -219,12 +237,24 @@ export async function reportLimitsOnce(cfg, log = () => {
         report = await fetchLimits(creds);
     }
     catch (error) {
-        log(`limits fetch failed: ${error.message}`);
+        log('warn', `limits fetch failed · ${error.message}`);
         return null;
     }
-    const ok = await postLimits(report, cfg);
-    if (!ok) {
-        log('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

@@ -2,22 +2,22 @@ import { defaultDesktopSessionsDir, defaultPiSessionsDirs, defaultProjectsDir }
 import { readStore, storePath } from './store.js';
 /** Matches the server's BatchSchema `.max(1000)`. */
 const MAX_BATCH = 1000;
+/** The hosted service. Only self-hosted deployments have to name an endpoint,
+ *  so setup on the hosted one is a token and nothing else. */
+export const DEFAULT_ENDPOINT = 'https://usagefleet.com';
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
 /** Resolve config from env first, then the stored settings (see store.ts). */
 export function loadConfig() {
     const file = readStore();
     // Use `||` (not `??`) so an empty-string env var falls back to the config
     // file — launchd/systemd units may inject empty USAGEFLEET_* values.
-    const endpoint = (process.env.USAGEFLEET_ENDPOINT || file.endpoint || '').replace(/\/+$/, '');
+    const endpoint = (process.env.USAGEFLEET_ENDPOINT || file.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, '');
     const token = process.env.USAGEFLEET_TOKEN || file.token || '';
-    if (!endpoint) {
-        throw new Error('USAGEFLEET_ENDPOINT is not set');
-    }
     if (!token) {
         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/hook.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { writeFileAtomic } from './atomic-write.js';
 import { claudeSettingsPath } from './paths.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. */
 const HOOK_TIMEOUT_S = 10;
@@ -71,7 +72,7 @@ function editSettings(transform, onWrite) {
             settings = parsed;
         }
         catch {
-            console.warn(`Could not parse ${path} — left it untouched. Fix the JSON and re-run.`);
+            console.log(warn('hook', `${tilde(path)} is not valid JSON · left untouched`));
             return;
         }
     }
@@ -96,8 +97,8 @@ export function installPromptHook(program) {
         return;
     }
     const command = guardCommand(program);
-    editSettings(s => withGuardHook(s, command), path => console.log(`Registered the over-limit prompt guard in ${path}.`));
+    editSettings(s => withGuardHook(s, command), path => console.log(step('hook', `prompt guard · ${tilde(path)}`)));
 }
 export function uninstallPromptHook() {
-    editSettings(withoutGuardHook, path => console.log(`Removed the prompt guard from ${path}.`));
+    editSettings(withoutGuardHook, path => console.log(step('removed', `prompt guard · ${tilde(path)}`)));
 }

package/dist/index.js

@@ -8,8 +8,8 @@ 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 { ago, bar, bold, dim, green, pct, row, state as stateLine, step, yellow } from './ui.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) {
     const prefix = `--${name}`;
@@ -27,22 +27,30 @@ function flag(name) {
     }
     return undefined;
 }
-function ts() {
-    return new Date().toISOString().replace('T', ' ').slice(0, 19);
-}
 /** "5h ██░░░░░░░░   2% · weekly ████░░░░░░  13%" — the shared limits line.
  *  Bars are plain characters, so they survive a service log as well as a TTY. */
 function limitsSummary(limits) {
     const models = limits.modelLimits.map(m => ` · ${m.model}(${m.window}) ${bar(m.pct, 6)} ${pct(m.pct)}`).join('');
     return `5h ${bar(limits.fiveHourPct)} ${pct(limits.fiveHourPct)} · weekly ${bar(limits.sevenDayPct)} ${pct(limits.sevenDayPct)}${models}`;
 }
+/** Every message the collector, notifier and self-update emit, as a stream
+ *  line. The level picks the glyph so a problem never reads like a result. */
+const stream = (level, m) => {
+    line(level === 'warn' ? yellow('!') : note, m);
+};
+/** Upload result as one stream line — the shape `run` and `watch` share.
+ *  Dropped records are the only part worth a colour: they are lost data. */
+function cycleLine(r) {
+    const dropped = r.dropped > 0 ? ` · ${yellow(`${r.dropped} dropped`)}` : '';
+    line(r.dropped > 0 ? yellow('!') : green('↑'), `${r.sent} sent ${dim(`· ${r.accepted} accepted · ${r.duplicates} dup · ${r.files} file${r.files === 1 ? '' : 's'}`)}${dropped}`);
+}
 async function cmdRun() {
     const cfg = loadConfig();
-    const r = await runOnce(cfg, m => console.log(`[${ts()}] ${m}`));
-    console.log(`[${ts()}] scanned ${r.files} files · sent ${r.sent} · accepted ${r.accepted} · duplicates ${r.duplicates}${r.dropped > 0 ? ` · DROPPED ${r.dropped}` : ''}${r.failed ? ' · FAILED' : ''}`);
-    const limits = await reportLimitsOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+    const r = await runOnce(cfg, stream);
+    cycleLine(r);
+    const limits = await reportLimitsOnce(cfg, stream);
     if (limits) {
-        console.log(`[${ts()}] limits (${limits.source}): ${limitsSummary(limits)}`);
+        line(note, `${limitsSummary(limits)} ${dim(`· ${limits.source}`)}`);
     }
     if (r.failed) {
         process.exitCode = 1;
@@ -50,12 +58,12 @@ async function cmdRun() {
 }
 async function cmdLimits() {
     const cfg = loadConfig();
-    const limits = await reportLimitsOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+    const limits = await reportLimitsOnce(cfg, stream);
     if (!limits) {
         process.exitCode = 1;
         return;
     }
-    console.log(`[${ts()}] reported ${limits.source}: ${limitsSummary(limits)}`);
+    line(note, `${limitsSummary(limits)} ${dim(`· ${limits.source}`)}`);
 }
 async function cmdWatch() {
     const cfg = loadConfig();
@@ -73,11 +81,10 @@ async function cmdWatch() {
     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;
     let lastUpdateAt = 0;
-    console.log(header());
-    console.log(dim(`[${ts()}] watching every ${interval / 1000}s → ${cfg.endpoint}`));
-    for (const dir of [cfg.projectsDir, cfg.desktopDir, ...cfg.piDirs].filter((d) => !!d)) {
-        console.log(dim(`           ${dir}`));
-    }
+    const watching = [cfg.projectsDir, cfg.desktopDir, ...cfg.piDirs].filter((d) => !!d);
+    console.log(header(`watching every ${interval / 1000}s`));
+    console.log(hint(`${watching.map(tilde).join(' · ')} → ${host(cfg.endpoint)}`));
+    console.log('');
     let stopping = false;
     let timer = null;
     let running = false;
@@ -87,27 +94,27 @@ async function cmdWatch() {
         }
         running = true;
         try {
-            const r = await runOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+            const r = await runOnce(cfg, stream);
             // Dropped records are real data loss, so they must show up even in a
             // cycle that uploaded nothing.
             if (r.sent > 0 || r.dropped > 0) {
-                console.log(`[${ts()}] ${r.dropped > 0 ? yellow('!') : green('↑')} sent ${r.sent} · accepted ${r.accepted} · dup ${r.duplicates}${r.dropped > 0 ? ` · ${yellow(`DROPPED ${r.dropped}`)}` : ''}`);
+                cycleLine(r);
             }
             const nowMs = Date.now();
             if (nowMs - lastUpdateAt >= updateInterval) {
                 lastUpdateAt = nowMs;
-                await checkForUpdate(m => console.log(`[${ts()}] ${m}`));
+                await checkForUpdate((level, m) => line(level === 'ok' ? blue('↻') : yellow('!'), m));
             }
             if (nowMs - lastLimitsAt >= limitsInterval) {
                 lastLimitsAt = nowMs;
-                const limits = await reportLimitsOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+                const limits = await reportLimitsOnce(cfg, stream);
                 if (limits) {
-                    console.log(`[${ts()}] limits (${limits.source}): ${limitsSummary(limits)}`);
+                    line(note, limitsSummary(limits));
                 }
             }
         }
         catch (error) {
-            console.error(`[${ts()}] cycle error:`, error.message);
+            line(yellow('!'), `cycle error ${dim(error.message)}`);
         }
         finally {
             running = false;
@@ -121,7 +128,7 @@ async function cmdWatch() {
         if (timer) {
             clearTimeout(timer);
         }
-        console.log(`\n[${ts()}] stopping…`);
+        line(note, dim('stopping…'));
         // Let an in-flight cycle finish committing offsets; hard-exit fallback.
         const bail = setTimeout(() => process.exit(0), 5000);
         bail.unref();
@@ -140,13 +147,13 @@ async function cmdWatch() {
 function cmdNotifyTest() {
     const cfg = loadNotifyConfig();
     if (!cfg.enabled) {
-        console.log('Notifications are disabled (USAGEFLEET_NOTIFY=0).');
+        console.log(warn('notify', 'disabled · unset USAGEFLEET_NOTIFY=0 to enable'));
         return;
     }
     sendNotification('usagefleet', 'Test notification — desktop alerts are working.', {
         urgency: 'normal',
     });
-    console.log(`[${ts()}] sent a test notification via ${detectOs()} (thresholds: ${cfg.thresholds.join(', ')}%)`);
+    console.log(step('notified', `${detectOs()} · thresholds ${cfg.thresholds.join(', ')}%`));
 }
 async function cmdStatus() {
     const cfg = loadConfig();
@@ -167,82 +174,110 @@ async function cmdStatus() {
         ? stateLine(limitHealth(limits.fiveHourPct, limits.sevenDayPct), 'limits', `5h ${bar(limits.fiveHourPct)} ${pct(limits.fiveHourPct)} · weekly ${bar(limits.sevenDayPct)} ${pct(limits.sevenDayPct)} ${dim(ago(limits.at))}`)
         : stateLine('warn', 'limits', `no reading yet ${dim('· run `usagefleet limits`')}`));
     console.log('');
-    console.log(row('endpoint', cfg.endpoint));
+    console.log(row('endpoint', host(cfg.endpoint)));
     console.log(row('device', `${state.deviceId} · token ${cfg.token.slice(0, 8)}…`));
     const watching = [cfg.projectsDir, cfg.desktopDir, ...cfg.piDirs].filter((d) => !!d);
     for (const [i, dir] of watching.entries()) {
-        console.log(row(i === 0 ? 'watching' : '', dir));
+        console.log(row(i === 0 ? 'watching' : '', tilde(dir)));
     }
     console.log(row('tracked', `${tracked} file${tracked === 1 ? '' : 's'} · ${mb} MB read · synced ${ago(state.updatedAt)}`));
-    console.log(row('config', cfg.storePath));
+    console.log(row('config', tilde(cfg.storePath)));
 }
 /** Worst of the two windows decides the dot colour. */
 function limitHealth(fiveHour, sevenDay) {
     const worst = Math.max(fiveHour ?? 0, sevenDay ?? 0);
     return worst >= 95 ? 'bad' : worst >= 80 ? 'warn' : 'ok';
 }
-/** "usagefleet 1.2.55  mac" — the one-line banner every command opens with. */
-function header() {
-    const build = RELEASE_VERSION === 'dev' ? dim(' (local build · self-update off)') : '';
-    return `${bold('usagefleet')} ${RELEASE_VERSION}${build}  ${dim(detectOs())}`;
+/** Setup in one command: persist the flags (when given), then install the
+ *  background service, which refuses to install without a resolvable token.
+ *  The write merges over the existing store, so re-running install rotates the
+ *  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) {
+        process.env.USAGEFLEET_ENDPOINT = endpoint;
+    }
+    if (token) {
+        process.env.USAGEFLEET_TOKEN = token;
+    }
+    const { install } = await import('./service.js');
+    install();
 }
-function cmdInit() {
-    const endpoint = flag('endpoint') ?? process.env.USAGEFLEET_ENDPOINT;
-    const token = flag('token') ?? process.env.USAGEFLEET_TOKEN;
-    if (!endpoint || !token) {
-        console.error('Usage: usagefleet init --endpoint <url> --token <device-token>');
-        process.exit(1);
+/** 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)}`);
     }
-    const path = storePath();
-    // Merges over whatever is already there, so tail offsets and projectsDir
-    // survive a re-init and the device does not re-upload its whole history.
-    updateStore(path, store => {
-        store.endpoint = endpoint;
-        store.token = token;
-    });
-    console.log(step('configured', `${endpoint} · ${path}`));
 }
+/** 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() {
-    console.log(`usagefleet ${RELEASE_VERSION} — Claude usage collector
-
-Usage:
-  usagefleet run                 Scan once, upload usage + report limits
-  usagefleet watch [--interval s] Poll continuously (default 15s)
-  usagefleet limits              Report only your real 5h/weekly limit usage
-  usagefleet guard               Exit 2 if this device's group is over a blocking limit
-                                   (use as a Claude Code UserPromptSubmit hook)
-  usagefleet update              Update to the latest release now (watch does this every 6h)
-  usagefleet notify-test         Fire a test desktop notification
-  usagefleet status              Show service health, limits, resolved config
-  usagefleet version             Print the release version
-  usagefleet init --endpoint <url> --token <t>   Write ~/.config/usagefleet/config.json
-  usagefleet install             Install as a background service (launchd/systemd/Task Scheduler)
-                                   and register the guard as a Claude Code hook
-  usagefleet uninstall           Remove the background service and the hook
-
-Config (env overrides ~/.config/usagefleet/config.json, which holds settings,
-tail offsets and notification marks; USAGEFLEET_CONFIG relocates it):
-  USAGEFLEET_ENDPOINT   server base URL (e.g. https://track.example.com)
-  USAGEFLEET_TOKEN      device token from the Devices page
-  USAGEFLEET_PROJECTS   override ~/.claude/projects (Claude Code)
-  USAGEFLEET_DESKTOP    override Claude Desktop sessions dir ("off" to disable)
-  USAGEFLEET_PI         override pi sessions dirs, comma-separated ("off" to disable)
-  USAGEFLEET_INTERVAL   watch interval seconds
-  USAGEFLEET_NOTIFY     desktop notifications on/off (default on; 0 to disable)
-  USAGEFLEET_HOOK       register the guard in ~/.claude/settings.json on install (0 to skip)
-  USAGEFLEET_UPDATE     self-update while watching (0 to disable)
-  USAGEFLEET_UPDATE_INTERVAL  seconds between update checks (default 21600 = 6h)
-  USAGEFLEET_NOTIFY_THRESHOLDS  comma list of % alerts (default 80,95)`);
+    const commands = [
+        ['run', 'scan once, upload usage + report limits'],
+        ['watch [--interval s]', 'poll continuously (default 15s)'],
+        ['limits', 'report only your real 5h/weekly usage'],
+        ['guard', 'exit 2 when the group is over a blocking limit'],
+        ['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'],
+    ];
+    console.log(header());
+    console.log('');
+    print(commands);
+    console.log('');
+    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
     // not silently kill the background service. One-shot commands still set a
     // non-zero exit via their own error paths.
     process.on('unhandledRejection', reason => {
-        console.error(`[${ts()}] unhandledRejection:`, reason);
+        line(yellow('!'), `unhandled rejection ${dim(String(reason))}`);
     });
     process.on('uncaughtException', err => {
-        console.error(`[${ts()}] uncaughtException:`, err.message);
+        line(yellow('!'), `uncaught exception ${dim(err.message)}`);
     });
     const cmd = process.argv[2] ?? 'help';
     switch (cmd) {
@@ -260,7 +295,9 @@ async function main() {
             return;
         }
         case 'update': {
-            await checkForUpdate(m => console.log(`[${ts()}] ${m}`), true);
+            console.log(header());
+            console.log('');
+            await checkForUpdate((level, m) => console.log(level === 'ok' ? step('update', m) : warn('update', m)), true);
             return;
         }
         case 'notify-test': {
@@ -269,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':
@@ -276,12 +316,10 @@ async function main() {
             console.log(RELEASE_VERSION);
             return;
         }
-        case 'init': {
-            return cmdInit();
-        }
+        // `init` was the separate config step; it now just does the whole setup.
+        case 'init':
         case 'install': {
-            const { install } = await import('./service.js');
-            return install();
+            return cmdInstall();
         }
         case 'uninstall': {
             const { uninstall } = await import('./service.js');
@@ -293,6 +331,6 @@ async function main() {
     }
 }
 main().catch(error => {
-    console.error(error.message);
+    console.error(fail('error', error.message));
     process.exit(1);
 });

package/dist/notifier.js

@@ -96,17 +96,17 @@ export function maybeNotify(report, cfg = loadNotifyConfig(), log = () => {
         const seven = evaluateWindow(state.sevenDay, report.sevenDayPct, report.sevenDayResetsAt, cfg.thresholds);
         if (five.fire != null) {
             sendNotification('Claude usage · 5-hour limit', `${report.fiveHourPct}% of your 5-hour limit used${resetSuffix(report.fiveHourResetsAt)}.`, { urgency: urgencyFor(five.fire) });
-            log(`notified: 5h at ${report.fiveHourPct}% (crossed ${five.fire}%)`);
+            log('ok', `notified · 5h at ${report.fiveHourPct}% · crossed ${five.fire}%`);
         }
         if (seven.fire != null) {
             sendNotification('Claude usage · weekly limit', `${report.sevenDayPct}% of your weekly limit used${resetSuffix(report.sevenDayResetsAt)}.`, { urgency: urgencyFor(seven.fire) });
-            log(`notified: weekly at ${report.sevenDayPct}% (crossed ${seven.fire}%)`);
+            log('ok', `notified · weekly at ${report.sevenDayPct}% · crossed ${seven.fire}%`);
         }
         updateStore(path, store => {
             store.notify = { fiveHour: five.next, sevenDay: seven.next };
         });
     }
     catch (error) {
-        log(`notify skipped: ${error.message}`);
+        log('warn', `notify skipped · ${error.message}`);
     }
 }