usagemax 0.3.6 → 0.3.8

package/README.md

@@ -16,6 +16,10 @@ integrations, use the documented [OpenAPI contract](https://usagemax.com/openapi
 or the public [agent surfaces](https://usagemax.com/?mode=agent); the package
 itself is intended to be invoked as a short-lived local process.
 
+See the repository's [SDK and integration surface](../../docs/sdk-ecosystem.md)
+for the supported client matrix. UsageMax does not advertise Python or Go
+packages until they are separately reviewed and published.
+
 ## Requirements
 
 - Node.js 20 or newer
@@ -26,22 +30,30 @@ itself is intended to be invoked as a short-lived local process.
 
 ```bash
 # Create a one-use code at https://usagemax.com/account.
-bunx usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX
 
 # npm users can run the same one-shot command with npx.
-npx --yes usagemax@latest link UMX-XXXX-XXXX-XXXX-XXXX
+npx --yes usagemax link UMX-XXXX-XXXX-XXXX-XXXX
 
 # Preview, then upload changed local usage.
 bunx usagemax sync --dry-run --explain
 bunx usagemax sync
 ```
 
+The CLI checks npm's `latest` dist-tag at most twice per day and never replaces
+itself silently. Run `usagemax update sync` to hand a command to the current
+release without typing `@latest`, or set `USAGEMAX_AUTO_UPDATE=1` for an
+explicit automatic handoff. Use `--no-update-check` or set
+`USAGEMAX_DISABLE_UPDATE_CHECK=1` in offline environments. Interactive
+terminals show a small stderr progress line; JSON,
+quiet, CI, and scheduled runs remain machine-readable and quiet.
+
 Agent-friendly checks can request JSON and keep the secret out of arguments and
 logs. This example only inspects local source coverage:
 
 ```bash
 set +x
-bunx usagemax doctor --deep --json | jq '{complete, sources: [.sources[] | {name, status}]}'
+bunx usagemax doctor --deep --json | jq '{complete: .inventoryComplete, sources: .detectedSources}'
 ```
 
 The JSON shape is intended for local automation; unsupported or unavailable
@@ -80,11 +92,14 @@ bunx usagemax sync --restart              # restart an expired saved upload
 bunx usagemax status --remote --json      # remote check; secret is never printed
 bunx usagemax doctor --deep --json        # parse and audit retained history
 bunx usagemax link UMX-… --no-sync        # link without uploading yet
+bunx usagemax --version --json             # print CLI and ccusage versions
+bunx usagemax update --json                # machine-readable release check
+bunx usagemax unlink --json                # safe automation result; no secret output
 ```
 
 ## Sources and coverage
 
-UsageMax pins [ccusage v20.0.20](https://github.com/ccusage/ccusage/releases/tag/v20.0.20)
+UsageMax pins [ccusage v20.0.23](https://github.com/ccusage/ccusage/releases/tag/v20.0.23)
 and supports its 16 adapters: Amp, Claude Code, Codebuff, Codex, GitHub Copilot
 CLI, Factory Droid, Gemini CLI, Goose, Grok Build, Hermes, Kilo Code, Kimi CLI,
 OpenClaw, OpenCode, Pi, and Qwen Code. Named Pi-format stores are discovered as
@@ -115,14 +130,15 @@ stdin; never pass it as an argument or put it in a URL:
 ```bash
 set +x
 printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
-  | bunx usagemax@latest token status \
+  | bunx usagemax token status \
       --device-id "$USAGEMAX_INSTALLATION_ID" \
       --json
 ```
 
-The `token status` command is included in CLI `0.3.6`. If the public npm tag
-does not yet contain `0.3.6`, run `node packages/cli/src/cli.js token status`
-from the UsageMax repository until that release is published.
+The `token status` command is included in CLI `0.3.8`. If a fresh environment
+still has an older npm tag, run `usagemax update token status` or
+`node packages/cli/src/cli.js token status` from this repository until the new
+package is published.
 
 The response is read-only and contains only status, type, scopes, profile/name,
 activation state, and a binding result of `unbound`, `bound`, `matched`, or
@@ -133,7 +149,7 @@ For a numeric-only result suitable for a smoke check:
 ```bash
 set +x
 printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
-  | bunx usagemax@latest token status \
+  | bunx usagemax token status \
       --device-id "$USAGEMAX_INSTALLATION_ID" --json \
   | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "keywords": [
     "usagemax",
@@ -38,6 +38,8 @@
     "src/installation.js",
     "src/sources.js",
     "src/transport.js",
+    "src/progress.js",
+    "src/updates.js",
     "src/resume.js",
     "src/service.js",
     "README.md",
@@ -55,6 +57,6 @@
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "ccusage": "20.0.20"
+    "ccusage": "20.0.23"
   }
 }

package/src/cli.js

@@ -13,10 +13,12 @@ import { fileURLToPath } from "node:url";
 import { prepareArchiveRecovery } from "./archives.js";
 import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, reportDateArgs, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
+import { createProgress } from "./progress.js";
 import { intervalMinutes, manageService, runScheduledSync } from "./service.js";
 import { collectorStatusView, requestCollectorStatus, requestSnapshot } from "./transport.js";
 import { resumeUpload, restartExpiredUpload, withConfigLock } from "./resume.js";
 import { CCUSAGE_VERSION, ccusageEnvironment, ccusageHome, discoverProviderArchives, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
+import { checkForUpdate, runLatest } from "./updates.js";
 
 // Make the short-lived collector recognizable in Activity Monitor and `ps`.
 // Windows may still display the underlying node.exe image name in Task Manager.
@@ -24,7 +26,7 @@ process.title = "UsageMax";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.6";
+const VERSION = "0.3.8";
 const PUBLIC_API_ORIGIN = "https://usagemax.com/api";
 const DEFAULT_LINK_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/link`;
 const DEFAULT_STATUS_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/status`;
@@ -118,17 +120,23 @@ function help() {
   process.stdout.write("           [--no-sync] [--name <name>]\n");
   process.stdout.write("  usagemax sync [--full] [--archives] [--restart] [--dry-run] [--explain] [--json]\n");
   process.stdout.write("                                  Reconcile once; --archives performs one-time recovery\n");
+  process.stdout.write("           [--quiet|--no-progress] [--check-updates|--no-update-check]  Control progress and the cached release check\n");
+  process.stdout.write("           [--json]                  Emit one JSON object per link/sync phase\n");
   process.stdout.write("  usagemax status                  Show local link status\n");
   process.stdout.write("           --remote [--json]        Verify the stored collector credential without printing it\n");
+  process.stdout.write("           [--quiet|--no-progress]  Disable interactive progress output\n");
   process.stdout.write("  usagemax token status [--device-id <uuid>] [--json]\n");
   process.stdout.write("                                  Diagnose a key piped on stdin; never pass it as an argument\n");
   process.stdout.write("  usagemax service install [--every 15]\n");
   process.stdout.write("                                  Opt into lightweight OS-scheduled sync\n");
   process.stdout.write("  usagemax service status|run|uninstall\n");
-  process.stdout.write("  usagemax doctor [--deep] [--json]\n");
+  process.stdout.write("  usagemax doctor [--deep] [--json] [--quiet|--no-progress]\n");
   process.stdout.write("                                  Check source coverage; --deep parses full history\n");
+  process.stdout.write("  usagemax update [command args]  Check npm and optionally run the latest CLI\n");
+  process.stdout.write("           [--json]                  Emit machine-readable update status\n");
   process.stdout.write("  usagemax report [...args]        Run a local ccusage report\n");
   process.stdout.write("  usagemax unlink [--revoke]       Remove locally; --revoke also disables uploads\n");
+  process.stdout.write("           [--json]                  Emit machine-readable unlink status\n");
 }
 
 function ccusageCliPath() {
@@ -170,13 +178,14 @@ function newerVersion(recommended) {
 
 function warnVersion(body) {
   if (newerVersion(body?.recommendedCliVersion)) {
-    process.stderr.write(`UsageMax ${body.recommendedCliVersion} is available. Run \`bunx usagemax@latest\` for current coverage fixes.\n`);
+    process.stderr.write(`UsageMax ${body.recommendedCliVersion} is available. Run \`usagemax update sync\` or set USAGEMAX_AUTO_UPDATE=1.\n`);
   }
 }
 
 async function link(args) {
   const code = normalizeLinkCode(args[0]);
   if (!code) throw new Error("Paste the one-use UMX link code shown at usagemax.com/account.");
+  const json = args.includes("--json");
   const configuredEndpoint = process.env.USAGEMAX_LINK_ENDPOINT || DEFAULT_LINK_ENDPOINT;
   const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
   if (!endpoint) throw new Error("USAGEMAX_LINK_ENDPOINT must use HTTPS, except for localhost development.");
@@ -218,28 +227,42 @@ async function link(args) {
   };
   await writeConfig(config);
   warnVersion(body);
-  process.stdout.write(`Linked ${savedName} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ linked: true, version: VERSION, deviceName: savedName, profileHandle: config.profileHandle || null, profileUrl: config.profileUrl, deviceIdConfigured: true, sync: args.includes("--no-sync") ? "skipped" : "started" })}\n`);
+  } else {
+    process.stdout.write(`Linked ${savedName} to ${config.profileHandle ? `@${config.profileHandle}` : "UsageMax"}.\n`);
+  }
   if (args.includes("--no-sync")) {
-    process.stdout.write("No usage was uploaded. Run `bunx usagemax sync --full` when you are ready.\n");
+    if (!json) process.stdout.write("No usage was uploaded. Run `bunx usagemax sync --full` when you are ready.\n");
     return;
   }
-  process.stdout.write("Running the first one-shot sync…\n");
-  await sync(["--full"], config);
+  if (!json) process.stdout.write("Running the first one-shot sync…\n");
+  await sync(["--full", ...(json ? ["--json"] : [])], config);
 }
 
 async function sync(args, suppliedConfig) {
-  const baseEnv = await ccusageEnvironment();
-  const recovery = args.includes("--archives")
-    ? await prepareArchiveRecovery(baseEnv)
-    : { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported: 0 };
+  const progress = createProgress({ json: args.includes("--json"), quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  progress.start("Preparing local usage sync…");
+  let recovery;
   try {
-    return await syncPrepared(args, suppliedConfig, recovery);
+    const baseEnv = await ccusageEnvironment();
+    recovery = args.includes("--archives")
+      ? await prepareArchiveRecovery(baseEnv)
+      : { archives: 0, cleanup: async () => undefined, env: baseEnv, unsupported: 0 };
+    return await syncPrepared(args, suppliedConfig, recovery, progress);
+  } catch (error) {
+    // Clear the transient line; the shared top-level handler prints one
+    // stable error message so failures are not duplicated.
+    progress.stop();
+    throw error;
   } finally {
-    await recovery.cleanup();
+    await recovery?.cleanup();
+    progress.stop();
   }
 }
 
-async function syncPrepared(args, suppliedConfig, recovery) {
+async function syncPrepared(args, suppliedConfig, recovery, progress = createProgress({ noProgress: true })) {
+  const startedAt = Date.now();
   const config = suppliedConfig || await readConfig();
   if (!config) throw new Error("This computer is not linked. Open https://usagemax.com/account and create a link code.");
   config.deviceId = await stableInstallationId(configDirectory(), config.deviceId);
@@ -253,27 +276,42 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     await writeConfig(config);
   }
   if (config.pendingSync) {
+    progress.update("Resuming the saved upload checkpoint…");
     if (dryRun) {
-      const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId };
+      const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId, cliVersion: VERSION, ccusageVersion: CCUSAGE_VERSION, durationMs: Date.now() - startedAt };
       process.stdout.write(json ? `${JSON.stringify(result)}\n` : `Dry run: saved run ${config.pendingSync.runId} awaits resume; no upload.\n`);
+      progress.succeed("Dry run complete; saved upload remains untouched.");
       return result;
     }
-    const result = await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
-    process.stdout.write(json ? `${JSON.stringify(result)}\n` : "Resumed and completed the saved sync. Run sync again to scan newer local changes.\n");
-    return result;
+    const result = await resumeUpload(config, {
+      save: writeConfig,
+      request: snapshotRequest,
+      warn: warnVersion,
+      onProgress: ({ index, total, operation, acknowledged }) => progress.update(`${acknowledged ? "Uploaded" : "Uploading"} ${index}/${total} · ${operation}`),
+    });
+    const summary = { ...result, cliVersion: VERSION, ccusageVersion: CCUSAGE_VERSION, durationMs: Date.now() - startedAt };
+    progress.succeed("Resumed and completed the saved sync.");
+    process.stdout.write(json ? `${JSON.stringify(summary)}\n` : "Resumed and completed the saved sync. Run sync again to scan newer local changes.\n");
+    return summary;
   }
   const inventory = await sourceInventory({ env: recovery.env, home: ccusageHome(recovery.env) });
+  progress.update(`Found ${inventory.sources.length} source${inventory.sources.length === 1 ? "" : "s"} and ${inventory.files}${inventory.truncated ? "+" : ""} local data file${inventory.files === 1 ? "" : "s"}.`);
   const today = new Date().toISOString().slice(0, 10);
   const knownSources = Array.isArray(config.knownSources) ? config.knownSources : [];
   const { bootstrap, full, skip, inventoryStable } = scanPolicy(config, inventory, {
     today, now: Date.now(), inventoryVersion: SOURCE_INVENTORY_VERSION, requestedFull, requestedArchives,
   });
   if (skip) {
-    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "partial" };
+    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "partial", skipReason: "inventory_unchanged", cliVersion: VERSION, ccusageVersion: CCUSAGE_VERSION, durationMs: Date.now() - startedAt };
     if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
-    else process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
+    else {
+      process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
+      if (explain) process.stdout.write(`Skipped because the source inventory fingerprint is unchanged; coverage remains ${result.coverage}.\n`);
+    }
+    progress.succeed("No local changes; upload skipped.");
     return;
   }
+  progress.update(`Parsing ${full ? "retained history" : "changed history"} with ccusage…`);
   const report = await ccusageJson(config, { env: recovery.env, full });
   // ccusage v20 exposes aggregates, not proof that every discovered file was
   // parsed. Inventory success alone cannot authorize destructive corrections.
@@ -309,17 +347,22 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     coverage: authoritative ? "complete" : "partial",
     coverageReason: "Parser does not certify complete source/day coverage; decreases and deletions are protected.",
     range: { from: days[0], to: days.at(-1) },
+    cliVersion: VERSION,
+    ccusageVersion: CCUSAGE_VERSION,
   };
+  progress.update(`Prepared ${partitions.length} usage chunk${partitions.length === 1 ? "" : "s"} and ${sessions.length} session identifier${sessions.length === 1 ? "" : "s"}.`);
   if (requestedArchives) {
     result.archives = recovery.archives;
     result.unsupportedArchives = recovery.unsupported;
   }
   if (dryRun) {
+    result.durationMs = Date.now() - startedAt;
     if (json) process.stdout.write(`${JSON.stringify({ ...result, dryRun: true })}\n`);
     else {
       process.stdout.write(`Dry run: ${partitions.length} partition(s), ${result.changedRows} changed row(s), ${sessions.length} private session identifiers, no upload.\n`);
       if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${regressions.length} protected regression(s). ${result.coverageReason}\n`);
     }
+    progress.succeed("Dry run complete; nothing uploaded.");
     return result;
   }
   const requests = [{ operation: "begin", payload: {
@@ -356,7 +399,14 @@ async function syncPrepared(args, suppliedConfig, recovery) {
   };
   config.lastSyncComplete = false;
   await writeConfig(config);
-  await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
+  await resumeUpload(config, {
+    save: writeConfig,
+    request: snapshotRequest,
+    warn: warnVersion,
+    onProgress: ({ index, total, operation, acknowledged }) => progress.update(`${acknowledged ? "Uploaded" : "Uploading"} ${index}/${total} · ${operation}`),
+  });
+  result.durationMs = Date.now() - startedAt;
+  progress.succeed(`Sync complete · ${partitions.length} chunk${partitions.length === 1 ? "" : "s"}, ${sessions.length} session identifier${sessions.length === 1 ? "" : "s"}.`);
   if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
   else {
     process.stdout.write(partitions.length || sessions.length
@@ -395,9 +445,10 @@ async function status(args = []) {
   const config = await readConfig();
   const remote = args.includes("--remote");
   const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
   if (!config) {
     if (json) {
-      process.stdout.write(`${JSON.stringify({ linked: false, remote: remote ? { status: "not_linked" } : undefined })}\n`);
+      process.stdout.write(`${JSON.stringify({ linked: false, version: VERSION, ccusageVersion: CCUSAGE_VERSION, configPath: configPath(), remote: remote ? { status: "not_linked" } : undefined })}\n`);
       return;
     }
     process.stdout.write("Not linked. Open https://usagemax.com/account to connect this computer.\n");
@@ -410,20 +461,29 @@ async function status(args = []) {
   }
   const local = {
     linked: true,
+    version: VERSION,
+    ccusageVersion: CCUSAGE_VERSION,
+    configPath: configPath(),
     deviceName: config.deviceName || deviceLabel(),
     profileHandle: config.profileHandle || null,
     deviceIdConfigured: Boolean(config.deviceId),
     lastSyncAt: config.lastSyncAt || null,
     lastFullSyncAt: config.lastFullSyncAt || null,
     pendingSync: config.pendingSync?.runId || null,
+    coverage: config.lastCoverage || null,
+    knownSources: Array.isArray(config.knownSources) ? config.knownSources : [],
+    snapshotRows: Object.keys(config.snapshots || {}).length,
     profileUrl: config.profileUrl || "https://usagemax.com/account",
   };
   let remoteView;
   if (remote) {
+    progress.start("Checking the stored collector credential…");
     try {
       const result = await requestCollectorStatus(collectorStatusEndpoint(config), config);
       remoteView = collectorStatusView(result.httpStatus, result.body, config.token);
+      progress.succeed("Remote credential checked.");
     } catch (error) {
+      progress.stop();
       remoteView = { tokenFormat: "valid", status: "unavailable", reason: error instanceof Error ? error.message : "Collector status unavailable." };
     }
     if (json) {
@@ -436,8 +496,11 @@ async function status(args = []) {
     return;
   }
   process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
+  process.stdout.write(`CLI: ${VERSION} · ccusage ${CCUSAGE_VERSION}\n`);
   process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
   process.stdout.write(`Last full reconciliation: ${config.lastFullSyncAt || "never"}\n`);
+  process.stdout.write(`Coverage: ${config.lastCoverage || "unknown"} · ${Object.keys(config.snapshots || {}).length} checkpoint rows\n`);
+  if (Array.isArray(config.knownSources) && config.knownSources.length) process.stdout.write(`Known sources: ${config.knownSources.join(", ")}\n`);
   if (config.pendingSync) process.stdout.write(`Pending sync: ${config.pendingSync.runId}; rerun sync to resume\n`);
   process.stdout.write(`Profile: ${config.profileUrl || "https://usagemax.com/account"}\n`);
   if (remote) printRemoteStatus(remoteView);
@@ -461,58 +524,87 @@ async function readTokenFromStdin() {
 async function tokenStatus(args = []) {
   const requestedDeviceId = option(args, "--device-id");
   if (requestedDeviceId && !DEVICE_PATTERN.test(requestedDeviceId)) throw new Error("--device-id must be a UUID.");
-  const token = await readTokenFromStdin();
+  const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  progress.start("Checking the collector credential…");
+  let token;
+  try {
+    token = await readTokenFromStdin();
+  } catch (error) {
+    progress.stop();
+    throw error;
+  }
   const configuredEndpoint = process.env.USAGEMAX_STATUS_ENDPOINT || DEFAULT_STATUS_ENDPOINT;
   const endpoint = validHttpsUrl(configuredEndpoint, { allowLocalhost: true });
-  if (!endpoint) throw new Error("USAGEMAX_STATUS_ENDPOINT must use HTTPS, except for localhost development.");
-  const result = await requestCollectorStatus(endpoint, { token, deviceId: requestedDeviceId });
-  const view = collectorStatusView(result.httpStatus, result.body, token);
-  if (args.includes("--json")) process.stdout.write(`${JSON.stringify(view)}\n`);
-  else {
-    process.stdout.write("Credential format: valid (umx_ + 64 lowercase hexadecimal characters)\n");
-    printRemoteStatus(view);
+  try {
+    if (!endpoint) throw new Error("USAGEMAX_STATUS_ENDPOINT must use HTTPS, except for localhost development.");
+    const result = await requestCollectorStatus(endpoint, { token, deviceId: requestedDeviceId });
+    const view = collectorStatusView(result.httpStatus, result.body, token);
+    progress.succeed("Collector credential checked.");
+    if (json) process.stdout.write(`${JSON.stringify(view)}\n`);
+    else {
+      process.stdout.write("Credential format: valid (umx_ + 64 lowercase hexadecimal characters)\n");
+      printRemoteStatus(view);
+    }
+  } catch (error) {
+    progress.stop();
+    throw error;
   }
 }
 
 async function doctor(args = []) {
-  const config = await readConfig();
-  const env = await ccusageEnvironment();
-  const inventory = await sourceInventory({ env, home: ccusageHome(env) });
-  const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
-  const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
-  const result = {
-    linked: Boolean(config),
-    homes,
-    detectedSources: inventory.sources,
-    files: inventory.files,
-    inventoryComplete: inventory.complete,
-    inventoryErrors: inventory.errors,
-    inventoryTruncated: inventory.truncated,
-    supportedSources: SUPPORTED_SOURCES,
-    archives: archives.length,
-    environment: platform() === "linux" && process.env.WSL_DISTRO_NAME ? `WSL ${process.env.WSL_DISTRO_NAME}` : platform(),
-    mode: args.includes("--deep") ? "deep" : "metadata-only",
-  };
-  if (args.includes("--deep")) {
-    const report = await ccusageJson(config, { env, full: true });
-    result.parsedSources = sourceSummary(report);
-    result.sessions = buildSessionPlan(report, config?.deviceId || "unlinked").length;
-  }
-  if (args.includes("--json")) {
-    process.stdout.write(`${JSON.stringify(result)}\n`);
-    return;
+  const json = args.includes("--json");
+  const progress = createProgress({ json, quiet: args.includes("--quiet"), noProgress: args.includes("--no-progress") });
+  progress.start(args.includes("--deep") ? "Auditing retained source history…" : "Inspecting local source coverage…");
+  try {
+    const config = await readConfig();
+    const env = await ccusageEnvironment();
+    const inventory = await sourceInventory({ env, home: ccusageHome(env) });
+    progress.update(`Found ${inventory.sources.length} source${inventory.sources.length === 1 ? "" : "s"} and ${inventory.files}${inventory.truncated ? "+" : ""} local data file${inventory.files === 1 ? "" : "s"}.`);
+    const archives = await discoverProviderArchives({ env, home: ccusageHome(env) });
+    const homes = String(env.USAGEMAX_DISCOVERED_HOMES || ccusageHome(env)).split(",").filter(Boolean);
+    const result = {
+      cliVersion: VERSION,
+      ccusageVersion: CCUSAGE_VERSION,
+      configPath: configPath(),
+      linked: Boolean(config),
+      homes,
+      detectedSources: inventory.sources,
+      files: inventory.files,
+      inventoryComplete: inventory.complete,
+      inventoryErrors: inventory.errors,
+      inventoryTruncated: inventory.truncated,
+      supportedSources: SUPPORTED_SOURCES,
+      archives: archives.length,
+      environment: platform() === "linux" && process.env.WSL_DISTRO_NAME ? `WSL ${process.env.WSL_DISTRO_NAME}` : platform(),
+      mode: args.includes("--deep") ? "deep" : "metadata-only",
+    };
+    if (args.includes("--deep")) {
+      progress.update("Parsing retained history with ccusage…");
+      const report = await ccusageJson(config, { env, full: true });
+      result.parsedSources = sourceSummary(report);
+      result.sessions = buildSessionPlan(report, config?.deviceId || "unlinked").length;
+    }
+    progress.succeed("Coverage check complete.");
+    if (json) {
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+      return;
+    }
+    process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
+    process.stdout.write(`Discovered homes: ${homes.length} (${homes.join(", ")})\n`);
+    process.stdout.write(`Detected sources: ${inventory.sources.join(", ") || "none"} (${inventory.files}${inventory.truncated ? "+" : ""} data files)\n`);
+    process.stdout.write(`Supported sources: ${SUPPORTED_SOURCES.join(", ")} (+ named pi-format stores)\n`);
+    if (platform() === "linux" && process.env.WSL_DISTRO_NAME) {
+      process.stdout.write(`Environment: WSL ${process.env.WSL_DISTRO_NAME}; readable Windows provider homes are included automatically\n`);
+    }
+    if (archives.length) process.stdout.write(`Recovery: ${archives.length} compressed provider archive(s) detected; run \`bunx usagemax sync --archives\` once to reconcile them\n`);
+    if (!inventory.complete) process.stdout.write(`Inventory: incomplete (${inventory.errors} read error(s)${inventory.truncated ? ", file limit reached" : ""}); no-change shortcut disabled\n`);
+    if (result.parsedSources) process.stdout.write(`Parsed sources: ${result.parsedSources.join(", ") || "none"}; ${result.sessions} private session identifiers\n`);
+    process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
+  } catch (error) {
+    progress.stop();
+    throw error;
   }
-  process.stdout.write(`Collector: ${config ? "linked" : "not linked"}\n`);
-  process.stdout.write(`Discovered homes: ${homes.length} (${homes.join(", ")})\n`);
-  process.stdout.write(`Detected sources: ${inventory.sources.join(", ") || "none"} (${inventory.files}${inventory.truncated ? "+" : ""} data files)\n`);
-  process.stdout.write(`Supported sources: ${SUPPORTED_SOURCES.join(", ")} (+ named pi-format stores)\n`);
-  if (platform() === "linux" && process.env.WSL_DISTRO_NAME) {
-    process.stdout.write(`Environment: WSL ${process.env.WSL_DISTRO_NAME}; readable Windows provider homes are included automatically\n`);
-  }
-  if (archives.length) process.stdout.write(`Recovery: ${archives.length} compressed provider archive(s) detected; run \`bunx usagemax sync --archives\` once to reconcile them\n`);
-  if (!inventory.complete) process.stdout.write(`Inventory: incomplete (${inventory.errors} read error(s)${inventory.truncated ? ", file limit reached" : ""}); no-change shortcut disabled\n`);
-  if (result.parsedSources) process.stdout.write(`Parsed sources: ${result.parsedSources.join(", ") || "none"}; ${result.sessions} private session identifiers\n`);
-  process.stdout.write(`Mode: one-shot, metadata no-op check, ${args.includes("--deep") ? "deep local parse" : "no log parsing"}\n`);
 }
 
 async function report(args) {
@@ -528,14 +620,55 @@ async function report(args) {
   if (code !== 0) process.exitCode = code;
 }
 
+async function update(args = []) {
+  const json = args.includes("--json");
+  const check = await checkForUpdate(configDirectory(), VERSION, { force: true });
+  if (!check.latest) {
+    const result = { version: VERSION, latest: null, newer: false, status: "unavailable" };
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${VERSION} · update check unavailable.\n`);
+    return;
+  }
+  if (!check.newer) {
+    const result = { version: VERSION, latest: check.latest, newer: false, status: "current" };
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${VERSION} is current.\n`);
+    return;
+  }
+  const result = { version: VERSION, latest: check.latest, newer: true, status: "available", command: "usagemax update sync" };
+  process.stdout.write(json ? `${JSON.stringify(result)}\n` : `UsageMax CLI ${check.latest} is available (current ${VERSION}).\n`);
+  const commandArgs = args.filter((arg) => arg !== "--check");
+  if (!commandArgs.length || args.includes("--check")) {
+    if (!json) process.stdout.write("Run `usagemax update sync` to hand off the next command to the latest npm release.\n");
+    return;
+  }
+  if (!json) process.stdout.write(`Launching UsageMax ${check.latest}…\n`);
+  return runLatest(commandArgs);
+}
+
+async function maybeUpdate(command, args) {
+  if (process.env.USAGEMAX_UPDATE_HANDOFF === "1" || process.env.USAGEMAX_DISABLE_UPDATE_CHECK === "1" || args.includes("--no-update-check")) return false;
+  if (!["sync", "link", "doctor"].includes(command)) return false;
+  const explicitCheck = args.includes("--check-updates");
+  if (!explicitCheck && args.includes("--json")) return false;
+  const check = await checkForUpdate(configDirectory(), VERSION, { force: explicitCheck });
+  if (!check.newer) return false;
+  if (process.env.USAGEMAX_AUTO_UPDATE === "1") {
+    await runLatest([command, ...args.filter((arg) => !["--check-updates", "--no-update-check"].includes(arg))]);
+    return true;
+  }
+  process.stderr.write(`UsageMax ${check.latest} is available. Run \`usagemax update ${command}\` or set USAGEMAX_AUTO_UPDATE=1.\n`);
+  return false;
+}
+
 async function removeLink(args = []) {
   const path = configPath();
   const config = await readConfig();
+  const json = args.includes("--json");
   if (!config) {
-    process.stdout.write("This computer is not linked.\n");
+    process.stdout.write(json ? `${JSON.stringify({ unlinked: false, reason: "not_linked" })}\n` : "This computer is not linked.\n");
     return;
   }
-  if (args.includes("--revoke")) {
+  const revoked = args.includes("--revoke");
+  if (revoked) {
     const endpoint = validHttpsUrl(config.revokeUrl, { allowLocalhost: true });
     if (!endpoint) throw new Error("This collector does not have a valid revoke endpoint. Revoke it at https://usagemax.com/account.");
     const response = await fetch(endpoint, {
@@ -549,16 +682,22 @@ async function removeLink(args = []) {
     if (!response.ok) throw new Error("UsageMax could not revoke this collector. It remains linked locally.");
   }
   await unlink(path);
-  process.stdout.write(args.includes("--revoke")
-    ? "Revoked this collector and removed its local key. Existing usage totals were retained.\n"
-    : "Removed the local UsageMax collector key. This computer's private installation identity was retained so relinking cannot duplicate its usage. Revoke the collector in your account if this computer is no longer trusted.\n");
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ unlinked: true, revoked, retainedInstallationIdentity: true })}\n`);
+  } else {
+    process.stdout.write(revoked
+      ? "Revoked this collector and removed its local key. Existing usage totals were retained.\n"
+      : "Removed the local UsageMax collector key. This computer's private installation identity was retained so relinking cannot duplicate its usage. Revoke the collector in your account if this computer is no longer trusted.\n");
+  }
 }
 
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0] || "sync";
   if (["--help", "-h", "help"].includes(command)) return help();
-  if (["--version", "-v"].includes(command)) return process.stdout.write(`${VERSION}\n`);
+  if (["--version", "-v"].includes(command)) return process.stdout.write(args.includes("--json") ? `${JSON.stringify({ version: VERSION, ccusageVersion: CCUSAGE_VERSION })}\n` : `${VERSION}\n`);
+  if (command === "update") return update(args.slice(1));
+  if (await maybeUpdate(command, args)) return;
   if (command === "service") {
     const action = args[1] || "status";
     const directory = option(args, "--config-dir") || configDirectory();

package/src/progress.js

@@ -0,0 +1,73 @@
+const FRAMES = ["·", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function canAnimate({ json = false, quiet = false, noProgress = false } = {}) {
+  return Boolean(process.stderr.isTTY)
+    && !json
+    && !quiet
+    && !noProgress
+    && process.env.USAGEMAX_NO_PROGRESS !== "1"
+    && process.env.CI !== "true";
+}
+
+/**
+ * A tiny stderr-only progress reporter. JSON and scheduled runs stay silent so
+ * stdout remains machine-readable and background jobs do not write a stream.
+ */
+export function createProgress(options = {}) {
+  const enabled = canAnimate(options);
+  let timer;
+  let frame = 0;
+  let active = false;
+  let last = "";
+  let startedAt = 0;
+
+  const elapsed = () => {
+    const seconds = Math.max(0, (Date.now() - startedAt) / 1000);
+    return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+  };
+
+  const render = (text) => {
+    if (!enabled || !active) return;
+    const line = `${FRAMES[frame % FRAMES.length]} ${text} · ${elapsed()}`;
+    frame += 1;
+    last = line;
+    process.stderr.write(`\r\x1b[2K${line}`);
+  };
+
+  return {
+    enabled,
+    start(text) {
+      if (!enabled) return;
+      active = true;
+      startedAt = Date.now();
+      render(text);
+      timer = setInterval(() => render(last.replace(/^[^ ]+ /, "").replace(/ · \d+(?:\.\d+)?s$/, "")), 120);
+      timer.unref?.();
+    },
+    update(text) {
+      if (!enabled) return;
+      if (!active) this.start(text);
+      else render(text);
+    },
+    succeed(text) {
+      if (!enabled) return;
+      const duration = elapsed();
+      this.stop();
+      process.stderr.write(`\r\x1b[2K✓ ${text} (${duration})\n`);
+    },
+    fail(text) {
+      if (!enabled) return;
+      const duration = elapsed();
+      this.stop();
+      process.stderr.write(`\r\x1b[2K✗ ${text} (${duration})\n`);
+    },
+    stop() {
+      if (!enabled) return;
+      if (timer) clearInterval(timer);
+      timer = undefined;
+      if (active) process.stderr.write("\r\x1b[2K");
+      active = false;
+      startedAt = 0;
+    },
+  };
+}

package/src/resume.js

@@ -1,7 +1,7 @@
 // A pending run is saved before network I/O. Persisting the acknowledged cursor
 // after each request permits replays when the response or local write is lost.
 // The server must receipt begin, chunks, sessions and complete idempotently.
-export async function resumeUpload(config, { save, request, warn = () => {} }) {
+export async function resumeUpload(config, { save, request, warn = () => {}, onProgress = () => {} }) {
   const pending = config.pendingSync;
   if (!pending || pending.version !== 1 || !Array.isArray(pending.requests)) {
     throw new Error("Invalid saved sync; preserve the config for recovery.");
@@ -9,10 +9,12 @@ export async function resumeUpload(config, { save, request, warn = () => {} }) {
   try {
     for (let index = pending.cursor; index < pending.requests.length; index += 1) {
       const { operation, payload } = pending.requests[index];
+      onProgress({ index: index + 1, total: pending.requests.length, operation });
       const response = await request(config, operation, payload, operation === "partitions" ? 60_000 : 30_000);
       warn(response);
       pending.cursor = index + 1;
       await save(config);
+      onProgress({ index: index + 1, total: pending.requests.length, operation, acknowledged: true });
     }
     // Commit local baseline and remove the journal in the same atomic write.
     const next = { ...config, ...pending.checkpoint };

package/src/sources.js

@@ -3,7 +3,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
-export const CCUSAGE_VERSION = "20.0.20";
+export const CCUSAGE_VERSION = "20.0.23";
 export const SOURCE_INVENTORY_VERSION = 3;
 export const SUPPORTED_SOURCES = [
   "amp",

package/src/updates.js

@@ -0,0 +1,99 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+export const REGISTRY_URL = "https://registry.npmjs.org/usagemax/latest";
+export const UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
+
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+export function compareVersions(left, right) {
+  const a = String(left || "").split(".").map(Number);
+  const b = String(right || "").split(".").map(Number);
+  if (a.length !== 3 || b.length !== 3 || a.some((part) => !Number.isInteger(part)) || b.some((part) => !Number.isInteger(part))) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] > b[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+function cachePath(directory) {
+  return join(directory, "update-check.json");
+}
+
+async function readCache(directory) {
+  try {
+    const value = record(JSON.parse(await readFile(cachePath(directory), "utf8")));
+    if (!value || !Number.isFinite(value.checkedAt)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(directory, value) {
+  await mkdir(dirname(cachePath(directory)), { recursive: true, mode: 0o700 });
+  const path = cachePath(directory);
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch(() => undefined);
+  }
+}
+
+export async function latestVersion({ fetchImpl = fetch, timeout = 1_500 } = {}) {
+  try {
+    const response = await fetchImpl(REGISTRY_URL, {
+      headers: { accept: "application/json" },
+      cache: "no-store",
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!response.ok) return null;
+    const body = record(await response.json());
+    return /^\d+\.\d+\.\d+$/.test(body?.version || "") ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check npm at most twice a day. A failed check is deliberately non-fatal.
+ * The result contains no account data and is safe to cache locally.
+ */
+export async function checkForUpdate(directory, currentVersion, { force = false, now = Date.now(), fetchImpl = fetch } = {}) {
+  const cached = await readCache(directory);
+  if (!force && cached && now - cached.checkedAt < UPDATE_CHECK_TTL_MS) {
+    return { ...cached, newer: compareVersions(cached.latest, currentVersion) > 0 };
+  }
+  const latest = await latestVersion({ fetchImpl });
+  const result = { checkedAt: now, latest: latest || cached?.latest || null };
+  await writeCache(directory, result).catch(() => undefined);
+  return { ...result, newer: compareVersions(result.latest, currentVersion) > 0 };
+}
+
+function runner() {
+  const override = process.env.USAGEMAX_PACKAGE_RUNNER?.trim();
+  if (override) return { command: override, prefix: [] };
+  if (process.env.npm_execpath) return { command: "npm", prefix: ["exec", "--yes"] };
+  return { command: "bunx", prefix: ["--bun"] };
+}
+
+/** Re-run a command through the current npm dist-tag without requiring @latest. */
+export async function runLatest(args, { spawnImpl = spawn } = {}) {
+  const selected = runner();
+  const child = spawnImpl(selected.command, [...selected.prefix, "usagemax@latest", "--", ...args], {
+    stdio: "inherit",
+    env: { ...process.env, USAGEMAX_UPDATE_HANDOFF: "1" },
+  });
+  const code = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (status) => resolve(status ?? 1));
+  });
+  process.exitCode = code;
+  return code;
+}