@usagefleet/cli 1.2.59 → 1.2.69

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.

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', `device outside your plan's device limit · free a slot or upgrade at ${cfg.endpoint}/devices · nothing is lost, uploads resume once it fits`);
             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';
@@ -204,12 +218,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 +232,12 @@ 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');
+        log('warn', 'limits upload failed');
     }
     // Cache the reading so `status` can show current usage without spending
     // another billable API call.

package/dist/config.js

@@ -2,17 +2,17 @@ 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');
     }

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

@@ -9,7 +9,7 @@ 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 { 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,95 @@ 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())}`;
-}
-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);
+/** 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() {
+    const endpoint = flag('endpoint');
+    const token = flag('token');
+    if (endpoint || token) {
+        updateStore(storePath(), store => {
+            if (endpoint) {
+                store.endpoint = endpoint;
+            }
+            if (token) {
+                store.token = token;
+            }
+        });
     }
-    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}`));
+    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. */
 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'],
+        ['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);
 }
 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 +280,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': {
@@ -276,12 +298,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 +313,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}`);
     }
 }

package/dist/release.js

@@ -1,8 +1,2 @@
-// Overwritten by .github/workflows/release.yml with the version being published
-// to npm. "dev" means "built locally", which disables self-update — a dev build
-// must never be replaced by a published one behind your back.
-// The annotation is load-bearing: without it the literal type would be 'dev'
-// here and '1.2.3' in CI, so every `=== '1.2.59'` check compiles locally and
-// fails the release build as a comparison with no overlap.
-// oxlint-disable-next-line typescript/no-inferrable-types -- see above
-export const RELEASE_VERSION = '1.2.59';
+// Generated by .github/workflows/release.yml.
+export const RELEASE_VERSION = "1.2.69";

package/dist/service.js

@@ -2,9 +2,10 @@ import { execFileSync } from 'node:child_process';
 import { chmodSync, existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { delimiter, join } from 'node:path';
+import { DEFAULT_ENDPOINT } from './config.js';
 import { installPromptHook, uninstallPromptHook } from './hook.js';
 import { readStore } from './store.js';
-import { row, step } from './ui.js';
+import { fail, header, hint, host, row, step, tilde, warn } from './ui.js';
 const LABEL = 'dev.usagefleet.collector';
 /** Scheduled Task name on Windows (mirrors the launchd label / systemd unit). */
 const TASK = 'usagefleet';
@@ -215,18 +216,23 @@ function xml(s) {
         .replaceAll("'", ''');
 }
 export function install() {
-    // Pre-flight: refuse to install a service that can't resolve an endpoint+token,
+    // Pre-flight: refuse to install a service that can't resolve a token,
     // otherwise the baked `watch` process throws on every launch and the service
     // manager crash-loops it invisibly (only the log file shows it). Use the same
-    // env-OR-file precedence loadConfig() uses so a prior `init` is honored.
+    // env-OR-file precedence loadConfig() uses so an earlier install's token is
+    // honored; the endpoint needs no check, it falls back to the hosted default.
     const file = readStore();
-    const endpoint = process.env.USAGEFLEET_ENDPOINT || file.endpoint || '';
+    const endpoint = process.env.USAGEFLEET_ENDPOINT || file.endpoint || DEFAULT_ENDPOINT;
     const token = process.env.USAGEFLEET_TOKEN || file.token || '';
-    if (!endpoint || !token) {
-        console.error('No endpoint/token resolved. Run `usagefleet init --endpoint <url> --token <t>` ' +
-            '(or set USAGEFLEET_ENDPOINT and USAGEFLEET_TOKEN) before installing.');
+    if (!token) {
+        console.error(fail('config', 'no device token resolved'));
+        console.error(hint('  usagefleet install --token <device-token>'));
+        console.error(hint('  or set USAGEFLEET_TOKEN'));
         process.exit(1);
     }
+    console.log(header());
+    console.log('');
+    console.log(step('configured', host(endpoint)));
     // Windows: stop a running task first, or `schtasks /run` below is ignored (the
     // task is IgnoreNew) — leaving the OLD version resident after an "update".
     if (process.platform === 'win32') {
@@ -238,8 +244,7 @@ export function install() {
     const prog = programArgs();
     const shadow = shadowingBinary(process.env.PATH, process.argv[1] ?? process.execPath);
     if (shadow) {
-        console.warn(`Another usagefleet is earlier on your PATH (${shadow}). The service below runs this one, ` +
-            `but your shell keeps running that one — delete it: rm ${shadow}`);
+        console.log(warn('path', `another usagefleet runs first · rm ${tilde(shadow)}`));
     }
     const env = presentEnv();
     // Same binary, different entry point: the service watches, the hook enforces.
@@ -276,7 +281,7 @@ ${envXml}
         mkdirSync(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true });
         mkdirSync(macLogDir(), { recursive: true });
         // 0600: this file carries USAGEFLEET_TOKEN and ANTHROPIC_API_KEY, the same
-        // secrets `init` deliberately writes at 0600.
+        // secrets the config file deliberately holds at 0600.
         writeFileSync(path, plist, { encoding: 'utf-8', mode: 0o600 });
         chmodSync(path, 0o600); // writeFileSync's mode does not apply to an existing file
         const domain = `gui/${process.getuid?.()}`;
@@ -313,7 +318,8 @@ ${envXml}
             /* best-effort */
         }
         console.log(step('service', 'launchd · starts at login'));
-        return;
+        console.log(row('logs', tilde(macLogDir())));
+        return collectingNow();
     }
     if (process.platform === 'linux') {
         // systemd: quote values, escape backslash/quote, reject newlines.
@@ -378,13 +384,12 @@ WantedBy=default.target
                 }
             }
             console.log(step('service', 'systemd · starts at login'));
+            return collectingNow();
         }
-        else {
-            console.log('Could not drive systemctl automatically. Enable it manually:');
-            console.log('  systemctl --user daemon-reload');
-            console.log('  systemctl --user enable --now usagefleet');
-            console.log('  loginctl enable-linger $USER   # keep running after logout');
-        }
+        console.log(warn('service', 'systemctl not driveable · enable it manually'));
+        console.log(hint('  systemctl --user daemon-reload'));
+        console.log(hint('  systemctl --user enable --now usagefleet'));
+        console.log(hint('  loginctl enable-linger $USER    keep running after logout'));
         return;
     }
     if (process.platform === 'win32') {
@@ -405,18 +410,26 @@ WantedBy=default.target
             schtasks('/create', '/tn', TASK, '/sc', 'onlogon', '/f', '/tr', `wscript.exe //B //Nologo "${vbsPath}"`);
         rmSync(xmlPath, { force: true });
         if (!created) {
-            console.error('Could not register the scheduled task. Register it manually:\n' +
-                `  schtasks /create /tn ${TASK} /sc onlogon /tr "wscript.exe //B //Nologo \\"${vbsPath}\\""`);
+            console.error(fail('service', 'scheduled task rejected · register it manually'));
+            console.error(hint(`  schtasks /create /tn ${TASK} /sc onlogon /tr "wscript.exe //B //Nologo \\"${vbsPath}\\""`));
             process.exit(1);
         }
         // Start now so install/update takes effect immediately, not at next logon.
         schtasks('/run', '/tn', TASK);
         console.log(step('service', 'scheduled task · starts at logon'));
-        console.log(row('logs', windowsLogPath()));
-        return;
+        console.log(row('logs', tilde(windowsLogPath())));
+        return collectingNow();
     }
-    console.log(`Unsupported platform for service install: ${process.platform}.`);
-    console.log(`Run it yourself with: ${prog.join(' ')}`);
+    console.log(warn('service', `no autostart on ${process.platform} · run it yourself`));
+    console.log(hint(`  ${prog.join(' ')}`));
+}
+/** Closing lines of a successful install: what is happening, and the two
+ *  commands worth knowing next. */
+function collectingNow() {
+    console.log('');
+    console.log(hint('collecting now.'));
+    console.log(hint('  usagefleet status    current state'));
+    console.log(hint('  usagefleet watch     foreground, live log'));
 }
 /** Is the background service actually up? This is the one question `status`
  *  has to answer, so every probe is best-effort: an unreadable or unparseable
@@ -491,7 +504,8 @@ export function uninstall() {
             }
         }
         removeStableBin();
-        console.log(`Removed launchd agent (delete ${path} to fully clean up).`);
+        console.log(step('removed', 'launchd agent'));
+        console.log(row('leftover', `${tilde(path)} · delete to fully clean up`));
         return;
     }
     if (process.platform === 'linux') {
@@ -504,7 +518,8 @@ export function uninstall() {
             /* ignore */
         }
         removeStableBin();
-        console.log(`Disabled systemd unit (delete ${systemdUnitPath()} to fully clean up).`);
+        console.log(step('removed', 'systemd unit'));
+        console.log(row('leftover', `${tilde(systemdUnitPath())} · delete to fully clean up`));
         return;
     }
     if (process.platform === 'win32') {
@@ -517,8 +532,8 @@ export function uninstall() {
             /* ignore */
         }
         removeStableBin();
-        console.log(deleted ? `Removed scheduled task "${TASK}".` : `No scheduled task "${TASK}" found.`);
+        console.log(deleted ? step('removed', `scheduled task ${TASK}`) : row('service', `no task ${TASK} found`));
         return;
     }
-    console.log(`Nothing to uninstall on ${process.platform}.`);
+    console.log(row('service', `nothing to uninstall on ${process.platform}`));
 }

package/dist/store.js

@@ -86,7 +86,7 @@ export function readStore(path = storePath()) {
 }
 /**
  * Read-modify-write the store atomically. Re-reading inside the call is what
- * lets `usagefleet init` change the token while the service is mid-cycle: the
+ * lets `usagefleet install` change the token while the service is mid-cycle: the
  * service's next save picks up the new token instead of overwriting it with the
  * copy it loaded minutes ago.
  *

package/dist/tailer.js

@@ -1,5 +1,6 @@
 import { closeSync, openSync, readSync, statSync } from 'node:fs';
 import { parseLine } from './parser.js';
+import { dim, line, tilde, yellow } from './ui.js';
 /** Max bytes read from a single file per cycle (bounds memory on huge backlogs). */
 const MAX_READ = 16 * 1024 * 1024;
 /**
@@ -38,7 +39,7 @@ export function tailFile(filePath, prev, source = 'cli') {
         // No newline in a full MAX_READ window = one pathologically long line.
         // Skip past it so the file can't stall forever.
         if (length >= MAX_READ) {
-            console.warn(`usagefleet: skipping a line > ${MAX_READ} bytes in ${filePath} at offset ${start}`);
+            line(yellow('!'), `skipped a line > ${MAX_READ} bytes ${dim(`· ${tilde(filePath)} at ${start}`)}`);
             return {
                 consumedBytes: length,
                 nextState: { ...base, offset: start + length },

package/dist/ui.js

@@ -1,35 +1,92 @@
 /**
- * Terminal output helpers, "quiet" style: one accent colour, detail in gray,
- * a padded label column so lines align.
+ * The CLI's only output surface, "quiet" style: lowercase labels, one accent
+ * colour, detail in gray, a padded label column so lines align. Every command
+ * — install, status, watch, the collector's own stream — prints through these
+ * helpers, so a TTY and a service log read the same.
  *
  * Colour is dropped when stdout is not a TTY (service logs, CI, pipes) or when
- * NO_COLOR is set. Bars are plain characters, so a log file still shows them.
+ * NO_COLOR is set. Glyphs and bars are plain characters, so a log file still
+ * shows them.
  */
+import { homedir } from 'node:os';
+import { detectOs } from './os.js';
+import { RELEASE_VERSION } from './release.js';
 const useColor = process.stdout.isTTY === true && !process.env.NO_COLOR;
 function paint(code) {
     return s => (useColor ? `\u001B[${code}m${s}\u001B[0m` : s);
 }
 export const dim = paint('90');
+/** One step below `dim`: timestamps, which are structure rather than content. */
+export const dimmer = paint('2;90');
 export const green = paint('32');
 export const yellow = paint('33');
 export const red = paint('31');
 export const blue = paint('34');
 export const bold = paint('1');
-/** Width of the label column shared by `step` and `row`. */
-const LABEL = 10;
-/** "✓ installed   ~/.local/bin/usagefleet" — a completed step. */
+/** Width of the label column shared by every labelled line. */
+const LABEL = 12;
+/** "usagefleet 1.2.55  mac-arm64" — the banner an interactive command opens
+ *  with. `detail` replaces the platform when a command has something better to
+ *  say about itself (watch states its interval). */
+export function header(detail = `${detectOs()}-${process.arch}`) {
+    const build = RELEASE_VERSION === 'dev' ? ' · local build, self-update off' : '';
+    return `${blue('usagefleet')} ${dim(`${RELEASE_VERSION}${build}  ${detail}`)}`;
+}
+/** Server without its scheme: the host is the part worth reading. */
+export function host(endpoint) {
+    return endpoint.replace(/^https?:\/\//, '').replace(/\/$/, '');
+}
+/** "✓ installed    ~/.local/bin/usagefleet" — a completed step. */
 export function step(label, detail = '') {
     return `${green('✓')} ${label.padEnd(LABEL)} ${dim(detail)}`;
 }
-/** "● service     running" — state with a health-coloured dot. */
+/** "✗ verify failed  expected 4f8c…" — a step that did not happen. */
+export function fail(label, detail = '') {
+    return `${red('✗')} ${label.padEnd(LABEL)} ${dim(detail)}`;
+}
+/** "! service      systemctl unavailable" — worked, but not fully. */
+export function warn(label, detail = '') {
+    return `${yellow('!')} ${label.padEnd(LABEL)} ${dim(detail)}`;
+}
+/** "● service      running" — state with a health-coloured dot. */
 export function state(health, label, detail) {
     const dot = health === 'ok' ? green('●') : health === 'warn' ? yellow('●') : red('●');
     return `${dot} ${label.padEnd(LABEL)} ${detail}`;
 }
-/** "  config      ~/.config/usagefleet/config.json" — a plain detail line. */
+/** "  config       ~/.config/usagefleet/config.json" — a plain detail line. */
 export function row(label, detail) {
     return `  ${label.padEnd(LABEL)} ${dim(detail)}`;
 }
+/** A closing suggestion, or any line that is context rather than result. */
+export function hint(text) {
+    return dim(text);
+}
+/** Home-relative path, because `~/.claude/projects` reads and wraps better than
+ *  the absolute one — and hides the user's account name in a pasted terminal. */
+export function tilde(path) {
+    const home = homedir();
+    return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+/** Day of the last printed stream line. The date is stated on rollover only:
+ *  HH:MM:SS alone is unreadable in a service log that spans a week, while a
+ *  one-shot command is already dated by the shell that ran it. */
+let lastDay = '';
+/**
+ * One line of the live stream: "09:14:02 ↑ 12 sent · 12 accepted".
+ * Used by `watch`, `run` and every message the collector emits, so the service
+ * log is the same stream a foreground run shows.
+ */
+export function line(glyph, text) {
+    const now = new Date();
+    const day = now.toLocaleDateString('en-CA');
+    if (lastDay && day !== lastDay) {
+        console.log(dimmer(`── ${day}`));
+    }
+    lastDay = day;
+    console.log(`${dimmer(now.toTimeString().slice(0, 8))} ${glyph} ${text}`);
+}
+/** Neutral stream glyph, for messages that are neither good nor bad news. */
+export const note = dim('·');
 /** Percentage as a fixed-width string, so successive log lines line up. */
 export function pct(value) {
     return `${value ?? '?'}%`.padStart(4);

package/dist/update.js

@@ -37,11 +37,14 @@ function run(cmd, args) {
  * install is worse than one that skips a release. `force` is the manual
  * `usagefleet update`, which ignores USAGEFLEET_UPDATE=0 but still refuses to
  * touch a dev build.
+ *
+ * `log` carries the level so the caller can pick the right glyph: the CLI
+ * renders progress as a step and every dead end as a warning.
  */
 export async function checkForUpdate(log, force = false) {
     if (RELEASE_VERSION === 'dev') {
         if (force) {
-            log('update: this is a dev build — install the published package first.');
+            log('warn', 'dev build · install the published package first');
         }
         return null;
     }
@@ -62,7 +65,7 @@ export async function checkForUpdate(log, force = false) {
         const res = await fetch(`${REGISTRY}/${PACKAGE}/latest`, { signal: AbortSignal.timeout(15_000) });
         if (!res.ok) {
             if (force) {
-                log(`update: registry has no release info (${res.status}).`);
+                log('warn', `registry has no release info (${res.status})`);
             }
             return null;
         }
@@ -70,7 +73,7 @@ export async function checkForUpdate(log, force = false) {
     }
     catch (error) {
         if (force) {
-            log(`update: cannot reach the npm registry (${error.message}).`);
+            log('warn', `npm registry unreachable · ${error.message}`);
         }
         return null;
     }
@@ -79,22 +82,22 @@ export async function checkForUpdate(log, force = false) {
     }
     if (latest === RELEASE_VERSION) {
         if (force) {
-            log(`update: already on ${RELEASE_VERSION}.`);
+            log('ok', `already current · ${RELEASE_VERSION}`);
         }
         return null;
     }
-    log(`update: ${RELEASE_VERSION} → ${latest}, installing ${PACKAGE}…`);
+    log('ok', `${RELEASE_VERSION} → ${latest} · installing ${PACKAGE}…`);
     const code = await run(npmCommand(), ['install', '--global', `${PACKAGE}@${latest}`]);
     if (code !== 0) {
-        log(code === null
-            ? 'update: npm is not available — reinstall with `npm i -g @usagefleet/cli`.'
-            : `update: npm install failed (exit ${code}) — if the global prefix needs root, run it yourself.`);
+        log('warn', code === null
+            ? 'npm not available · reinstall with `npm i -g @usagefleet/cli`'
+            : `npm install failed (exit ${code}) · if the global prefix needs root, run it yourself`);
         return null;
     }
     // Detached: `install` rewrites the service definition and restarts it, which
     // kills this process tree. npm replaced the file behind `self`, so this is
     // already the new version.
     spawn(process.execPath, [self, 'install'], { detached: true, stdio: 'ignore' }).unref();
-    log(`update: installed ${latest}, restarting service.`);
+    log('ok', `installed ${latest} · restarting service`);
     return latest;
 }

package/dist/uploader.js

@@ -52,7 +52,10 @@ function classifyClientError(status) {
     if (status === 400 || status === 422) {
         return 'invalid';
     }
-    return 'transient'; // 402 outside plan, 404, 408, 413, … — the data is fine
+    if (status === 402) {
+        return 'plan';
+    }
+    return 'transient'; // 404, 408, 413, … — the data is fine
 }
 /** Parse a Retry-After header (delta-seconds OR HTTP-date), clamped to [0, 60s]. */
 function retryAfterMs(header, fallback) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@usagefleet/cli",
-	"version": "1.2.59",
+	"version": "1.2.69",
 	"description": "Tails Claude Code, Claude Desktop, and pi agent JSONL logs and reports token usage to a UsageFleet server.",
 	"keywords": [
 		"claude",
@@ -11,6 +11,11 @@
 	],
 	"homepage": "https://usagefleet.com",
 	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/rokartur/usagefleet.git",
+		"directory": "apps/cli"
+	},
 	"bin": {
 		"usagefleet": "dist/index.js"
 	},