@vibe-cafe/vibe-usage 0.10.24 → 0.10.25

package/README.md

@@ -4,31 +4,37 @@ Track your AI coding tool token usage and sync to [vibecafe.ai](https://vibecafe
 
 ## Quick Start
 
+One command, nothing to configure:
+
 ```bash
 npx @vibe-cafe/vibe-usage
 ```
 
-That's it. The CLI opens [vibecafe.ai/usage/device](https://vibecafe.ai/usage/device) in your browser; sign in, confirm the verification code shown in your terminal, click 「确认链接」, and the CLI receives an API key automatically.
+On the first run it:
+1. Opens [vibecafe.ai/usage/device](https://vibecafe.ai/usage/device) in your browser — sign in, confirm the code shown in the terminal, click 「确认链接」; the key is saved to `~/.vibe-usage/config.json`
+2. Detects the AI coding tools installed on this machine
+3. Uploads your usage history
+4. Turns on background sync (every 30 minutes, starts at login) — no prompt, nothing else to install
+
+Run the same command again any time to sync right now. To turn background sync off: `npx @vibe-cafe/vibe-usage daemon uninstall`. Add `--no-daemon` to the first run if you don't want the background service at all.
 
-After approval, it will:
-1. Save your API key to `~/.vibe-usage/config.json`
-2. Detect installed AI coding tools
-3. Run an initial sync of your usage data
-4. Prompt you to enable the background daemon for continuous syncing (recommended)
+Prefer a menu-bar app? [Vibe Usage for Mac](https://github.com/vibe-cafe/vibe-usage-app) · [for Windows](https://github.com/vibe-cafe/vibe-usage-windows).
 
 ### CI / Headless
 
-If you don't have a local browser (CI, remote SSH session, container), pre-issue a key at [vibecafe.ai/usage/setup](https://vibecafe.ai/usage/setup) and pass it on the command line:
+If you don't have a local browser (CI, remote SSH session, container), pre-issue a key at [vibecafe.ai/usage/setup](https://vibecafe.ai/usage/setup) and pass it on the command line. Non-interactive runs never install the background service:
 
 ```bash
-npx @vibe-cafe/vibe-usage init --manual-key vbu_xxxxxxxxxxxx
+npx @vibe-cafe/vibe-usage init --manual-key vbu_xxxxxxxxxxxx --no-daemon
 ```
 
-## Commands
+<details>
+<summary><strong>All commands</strong> — everything below still works; the older spellings print a hint pointing at the simpler form</summary>
 
 ```bash
-npx @vibe-cafe/vibe-usage              # Init (first run, browser login) or sync (subsequent runs)
-npx @vibe-cafe/vibe-usage init         # Re-run setup via browser login
+npx @vibe-cafe/vibe-usage              # Init (first run, browser login, then background sync) or sync (subsequent runs)
+npx @vibe-cafe/vibe-usage --no-daemon  # Same, but skip installing the background service on first run
+npx @vibe-cafe/vibe-usage init         # Re-run setup via browser login (also how you re-bind to another account)
 npx @vibe-cafe/vibe-usage init --manual-key <vbu_...>   # Skip browser, use pre-issued key (CI/headless)
 npx @vibe-cafe/vibe-usage sync         # Manual sync
 npx @vibe-cafe/vibe-usage sync --extra-codex-home /path/to/.codex  # Add another Codex Home for this run only
@@ -45,8 +51,11 @@ npx @vibe-cafe/vibe-usage reset --local  # Delete this host's data only and re-u
 npx @vibe-cafe/vibe-usage skill         # Install skill for AI coding assistants
 npx @vibe-cafe/vibe-usage skill --remove  # Remove installed skills
 npx @vibe-cafe/vibe-usage status       # Show config & detected tools
+npx @vibe-cafe/vibe-usage help --all   # Full help (plain `help` shows the short version)
 ```
 
+</details>
+
 ## Supported Tools
 
 | Tool | Data Location |
@@ -93,7 +102,7 @@ npx @vibe-cafe/vibe-usage status       # Show config & detected tools
 - Incremental Codex parsing: a versioned, disposable cache under `~/.vibe-usage/cache/codex/` stores per-rollout aggregate results and parser continuation state. Unchanged rollouts require no raw-log reads; an ordinary append reads only the new tail; forks, sub-agents, replacements, truncations, and failed safety checks fall back to the full correctness path. A bounded rolling audit occasionally re-reads one historical file. Very large first-time indexes checkpoint before the Mac app timeout and resume on the next sync instead of restarting
 - The Codex parser cache contains derived aggregates and replay metadata, not raw prompt or response text. It is independent of upload state and can be deleted safely (the next sync rebuilds it). `reset` intentionally keeps it so the required full re-upload does not also require a full disk rescan. Set `VIBE_USAGE_CODEX_CACHE=0` to disable the optimization for diagnosis
 - SQLite-backed tools are read via Node's built-in `node:sqlite` on Node ≥ 22.5 — no `sqlite3` binary needed (works on Windows out of the box); on older Node the CLI falls back to the system `sqlite3` executable
-- For continuous syncing, use `npx @vibe-cafe/vibe-usage daemon` or the [Vibe Usage Mac app](https://github.com/vibe-cafe/vibe-usage-app)
+- Continuous syncing is on by default: the first run installs a background service (see [Background sync](#background-sync)); the [Vibe Usage Mac app](https://github.com/vibe-cafe/vibe-usage-app) is the menu-bar alternative
 
 ## Cursor 网络排查
 
@@ -211,36 +220,30 @@ npx @vibe-cafe/vibe-usage config remove-root grok /path/to/grok-home
 
 Default roots are always scanned and existing `codexExtraHome` configurations remain valid. Additional roots are only scanned after they are explicitly added. If a configured root later becomes unavailable, that tool is skipped for the current sync so its incremental upload state is not pruned.
 
-## Daemon Mode
-
-### Background service (recommended)
+## Background sync
 
-Install as a system service for automatic background syncing:
+The first `npx @vibe-cafe/vibe-usage` run installs a user-level service (systemd on Linux, launchd on macOS, Task Scheduler on Windows — no admin rights needed) that syncs every 30 minutes and starts automatically on login. Nothing else to do.
 
-```bash
-npx @vibe-cafe/vibe-usage daemon install
-```
-
-This creates a user-level service (systemd on Linux, launchd on macOS, Task Scheduler on Windows — no admin rights needed) that syncs every 30 minutes and starts automatically on login. Manage with:
+<details>
+<summary>Managing the service, and how it is launched</summary>
 
 ```bash
 npx @vibe-cafe/vibe-usage daemon status
 npx @vibe-cafe/vibe-usage daemon stop
 npx @vibe-cafe/vibe-usage daemon restart
 npx @vibe-cafe/vibe-usage daemon uninstall
+npx @vibe-cafe/vibe-usage daemon install    # only needed after --no-daemon or uninstall
 ```
 
-For reliable operation, install globally first: `npm install -g @vibe-cafe/vibe-usage`
-
-### Foreground mode
+**How the service starts the CLI.** When you ran the CLI through `npx`, the service is registered as `npx --yes @vibe-cafe/vibe-usage@latest daemon`, so it survives `npm cache clean` and picks up the newest release at every login. When the CLI was installed globally (`npm install -g @vibe-cafe/vibe-usage`) or run from a checkout, the service pins that exact `node <bin> daemon` path instead — upgrade the package and `daemon restart` to pick up a new version. `daemon status` prints which of the two forms a machine has. A service installed by a CLI older than 0.10.25 keeps its pinned npx-cache path; to switch it to the self-updating form run `daemon uninstall` and then the bare command once.
 
-Run continuous syncing in the foreground (every 30 minutes):
+**Foreground mode** (no service, Ctrl+C to stop):
 
 ```bash
 npx @vibe-cafe/vibe-usage daemon
 ```
 
-Press Ctrl+C to stop.
+</details>
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-cafe/vibe-usage",
-  "version": "0.10.24",
+  "version": "0.10.25",
   "description": "Track your AI coding tool token usage and sync to vibecafe.ai",
   "type": "module",
   "scripts": {

package/src/daemon-service.js

@@ -1,12 +1,16 @@
 import { execFileSync } from 'node:child_process';
 import { writeFileSync, readFileSync, unlinkSync, mkdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname, win32 as winPath } from 'node:path';
 import { homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { success, failure, warn, dim } from './output.js';
 
 const SERVICE_NAME = 'vibe-usage';
 const LAUNCHD_LABEL = 'ai.vibecafe.vibe-usage';
+// Same specifier the Mac app resolves on every sync (vibe-usage-app
+// RuntimeDetector.swift): a service that runs this instead of a pinned bin
+// path survives npx cache cleanup and picks up new releases at each login.
+export const PACKAGE_SPEC = '@vibe-cafe/vibe-usage@latest';
 
 function detectPlatform() {
   const os = platform();
@@ -23,16 +27,45 @@ function detectPlatform() {
   return null;
 }
 
+// npx cache paths are unstable — a service pinned to one breaks when the
+// cache is cleared. POSIX: ~/.npm/_npx/<hash>/...; Windows:
+// %LocalAppData%\npm-cache\_npx\...
+export function isNpxCachePath(binPath) {
+  return /[\\/]_npx[\\/]/.test(binPath);
+}
+
+/**
+ * When the CLI itself came from the npx cache, the service should not pin
+ * that path; it should re-resolve the package through npx at every start.
+ * Returns null when no npx lives next to the running node (then the caller
+ * falls back to pinning the path and warning, as before).
+ */
+export function npxLauncher(nodePath, exists = existsSync, os = platform()) {
+  const nodeDir = dirname(nodePath);
+  const npxPath = join(nodeDir, os === 'win32' ? 'npx.cmd' : 'npx');
+  return exists(npxPath) ? { mode: 'npx', npxPath, nodeDir } : null;
+}
+
 function resolvePaths() {
   const nodePath = process.execPath;
   const thisFile = fileURLToPath(import.meta.url);
   const binPath = join(thisFile, '..', '..', 'bin', 'vibe-usage.js');
+  const isNpxCache = isNpxCachePath(binPath);
+  const launcher = isNpxCache ? npxLauncher(nodePath) : null;
+  return { nodePath, binPath, isNpxCache, launcher };
+}
 
-  // npx cache paths are unstable — service will break when cache is cleared.
-  // POSIX: ~/.npm/_npx/<hash>/...; Windows: %LocalAppData%\npm-cache\_npx\...
-  const isNpxCache = /[\\/]_npx[\\/]/.test(binPath);
+// argv the service runs; the last token is always `daemon` so process
+// matching and log greps keep working across both modes.
+function serviceArgv(nodePath, binPath, launcher) {
+  if (launcher?.mode === 'npx') return [launcher.npxPath, '--yes', PACKAGE_SPEC, 'daemon'];
+  return [nodePath, binPath, 'daemon'];
+}
 
-  return { nodePath, binPath, isNpxCache };
+// npx is a `#!/usr/bin/env node` script and launchd / systemd start services
+// with a minimal PATH that has no node on it.
+function servicePath(launcher) {
+  return [launcher.nodeDir, '/usr/local/bin', '/usr/bin', '/bin'].join(':');
 }
 
 function getServicePaths(plat) {
@@ -103,21 +136,26 @@ export function generateSystemdUnit(
   binPath,
   claudeConfigDir = process.env.CLAUDE_CONFIG_DIR?.trim(),
   env = process.env,
+  launcher = null,
 ) {
+  const npx = launcher?.mode === 'npx';
+  const pathLine = npx ? `Environment="PATH=${escapeSystemdEnvironment(servicePath(launcher))}"\n` : '';
   const environment = serviceEnvironment(claudeConfigDir, env)
     .map(([key, value]) => `Environment="${key}=${escapeSystemdEnvironment(value)}"\n`)
     .join('');
+  // npx mode needs the registry at start; RestartSec=60 keeps an offline boot
+  // from turning into a restart storm.
   return `[Unit]
 Description=VibeCafe Usage Tracker
 After=network.target
 
 [Service]
 Type=simple
-ExecStart=${nodePath} ${binPath} daemon
+ExecStart=${serviceArgv(nodePath, binPath, launcher).join(' ')}
 Restart=on-failure
-RestartSec=10
+RestartSec=${npx ? 60 : 10}
 Environment=NODE_ENV=production
-${environment}WorkingDirectory=${homedir()}
+${pathLine}${environment}WorkingDirectory=${homedir()}
 
 [Install]
 WantedBy=default.target
@@ -129,11 +167,22 @@ export function generateLaunchdPlist(
   binPath,
   claudeConfigDir = process.env.CLAUDE_CONFIG_DIR?.trim(),
   env = process.env,
+  launcher = null,
 ) {
+  const npx = launcher?.mode === 'npx';
   const logDir = join(homedir(), '.vibe-usage');
+  const programArguments = serviceArgv(nodePath, binPath, launcher)
+    .map(arg => `        <string>${escapeXml(arg)}</string>\n`)
+    .join('');
+  const pathEntry = npx
+    ? `        <key>PATH</key>\n        <string>${escapeXml(servicePath(launcher))}</string>\n`
+    : '';
   const environment = serviceEnvironment(claudeConfigDir, env)
     .map(([key, value]) => `        <key>${key}</key>\n        <string>${escapeXml(value)}</string>\n`)
     .join('');
+  // ThrottleInterval only matters in npx mode: an offline boot makes npx exit
+  // non-zero and KeepAlive would otherwise relaunch it every 10 seconds.
+  const throttle = npx ? `    <key>ThrottleInterval</key>\n    <integer>60</integer>\n` : '';
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -142,15 +191,12 @@ export function generateLaunchdPlist(
     <string>${LAUNCHD_LABEL}</string>
     <key>ProgramArguments</key>
     <array>
-        <string>${nodePath}</string>
-        <string>${binPath}</string>
-        <string>daemon</string>
-    </array>
+${programArguments}    </array>
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
     <true/>
-    <key>WorkingDirectory</key>
+${throttle}    <key>WorkingDirectory</key>
     <string>${homedir()}</string>
     <key>StandardOutPath</key>
     <string>${join(logDir, 'daemon.log')}</string>
@@ -160,7 +206,7 @@ export function generateLaunchdPlist(
     <dict>
         <key>NODE_ENV</key>
         <string>production</string>
-${environment}    </dict>
+${pathEntry}${environment}    </dict>
 </dict>
 </plist>
 `;
@@ -171,6 +217,7 @@ export function generateWindowsTaskCmd(
   binPath,
   claudeConfigDir = process.env.CLAUDE_CONFIG_DIR?.trim(),
   env = process.env,
+  launcher = null,
 ) {
   const logPath = join(homedir(), '.vibe-usage', 'daemon.log');
   const lines = [
@@ -178,12 +225,17 @@ export function generateWindowsTaskCmd(
     'rem Generated by `vibe-usage daemon install` - reinstalling overwrites this file',
     'set "NODE_ENV=production"',
   ];
+  if (launcher?.mode === 'npx') {
+    // npx.cmd re-launches node by name; the logon task's PATH may not have it.
+    lines.push(`set "PATH=${escapeCmdValue(launcher.nodeDir)};%PATH%"`);
+  }
   for (const [key, value] of serviceEnvironment(claudeConfigDir, env)) {
     lines.push(`set "${key}=${escapeCmdValue(value)}"`);
   }
-  lines.push(
-    `"${escapeCmdValue(nodePath)}" "${escapeCmdValue(binPath)}" daemon >> "${escapeCmdValue(logPath)}" 2>&1`,
-  );
+  const invocation = launcher?.mode === 'npx'
+    ? `"${escapeCmdValue(launcher.npxPath)}" --yes ${PACKAGE_SPEC} daemon`
+    : `"${escapeCmdValue(nodePath)}" "${escapeCmdValue(binPath)}" daemon`;
+  lines.push(`${invocation} >> "${escapeCmdValue(logPath)}" 2>&1`);
   return lines.join('\r\n') + '\r\n';
 }
 
@@ -300,13 +352,26 @@ function windowsUserId() {
 // invocation. Process matching uses both paths so it works for Node and Bun
 // without touching foreground daemons from another checkout.
 export function parseWindowsTaskInvocation(cmd) {
-  const match = cmd.match(/^"([^"]+)" "([^"]+)" daemon\b/m);
-  if (!match) return null;
   const unescapeCmdValue = value => value.replace(/%%/g, '%');
-  return {
-    runtimePath: unescapeCmdValue(match[1]),
-    binPath: unescapeCmdValue(match[2]),
-  };
+  const pinned = cmd.match(/^"([^"]+)" "([^"]+)" daemon\b/m);
+  if (pinned) {
+    return {
+      runtimePath: unescapeCmdValue(pinned[1]),
+      binPath: unescapeCmdValue(pinned[2]),
+    };
+  }
+  // npx mode: the live daemon is node.exe (next to npx.cmd) running the
+  // cached bin, whose path we cannot know in advance — match on the bin name.
+  const npx = cmd.match(/^"([^"]+)" --yes @vibe-cafe\/vibe-usage@\S+ daemon\b/m);
+  if (npx) {
+    const npxPath = unescapeCmdValue(npx[1]);
+    return {
+      runtimePath: winPath.join(winPath.dirname(npxPath), 'node.exe'),
+      binPath: 'vibe-usage.js',
+      mode: 'npx',
+    };
+  }
+  return null;
 }
 
 function readTaskInvocation(paths) {
@@ -336,6 +401,36 @@ function daemonProcessKillLines(invocation) {
     : [];
 }
 
+export function isDaemonPlatform() {
+  return detectPlatform() !== null;
+}
+
+// A leftover daemon-task.xml without a registration (crashed uninstall) must
+// not block a fresh install, so Task Scheduler checks the live task instead.
+export function isDaemonInstalled() {
+  const plat = detectPlatform();
+  if (!plat) return false;
+  const paths = getServicePaths(plat);
+  return plat === 'taskscheduler' ? taskExists() : existsSync(paths.file);
+}
+
+// How an installed service starts the daemon, read back from the unit itself
+// so `status` tells the truth about machines set up by older versions. The
+// plist splits argv into separate <string> elements, so look for the package
+// spec alone: a pinned bin path contains `@vibe-cafe/vibe-usage/bin`, never
+// `@latest`.
+export function installedModeFromText(text) {
+  return text.includes(PACKAGE_SPEC) ? 'npx' : 'pinned';
+}
+
+export function describeInstalledMode(plat, paths) {
+  try {
+    return installedModeFromText(readFileSync(plat === 'taskscheduler' ? paths.cmd : paths.file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
 function install() {
   const plat = detectPlatform();
   if (!plat) {
@@ -344,20 +439,17 @@ function install() {
     return;
   }
 
-  const { nodePath, binPath, isNpxCache } = resolvePaths();
+  const { nodePath, binPath, isNpxCache, launcher } = resolvePaths();
 
-  if (isNpxCache) {
-    console.log(warn('检测到从 npx 缓存运行 vibe-usage,缓存清理后 daemon 会失效。'));
+  if (isNpxCache && !launcher) {
+    console.log(warn('检测到从 npx 缓存运行 vibe-usage 且找不到 npx,缓存清理后 daemon 会失效。'));
     console.log(dim('  建议先全局安装:  npm install -g @vibe-cafe/vibe-usage'));
     console.log();
   }
 
   const paths = getServicePaths(plat);
 
-  // A leftover daemon-task.xml without a registration (crashed uninstall) must
-  // not block a fresh install, so Task Scheduler checks the live task instead
-  const alreadyInstalled = plat === 'taskscheduler' ? taskExists() : existsSync(paths.file);
-  if (alreadyInstalled) {
+  if (isDaemonInstalled()) {
     console.log(warn('Daemon 已安装，运行 `vibe-usage daemon restart` 或 `uninstall` 先处理。'));
     return;
   }
@@ -365,7 +457,7 @@ function install() {
   mkdirSync(paths.dir, { recursive: true });
 
   if (plat === 'systemd') {
-    writeFileSync(paths.file, generateSystemdUnit(nodePath, binPath), 'utf-8');
+    writeFileSync(paths.file, generateSystemdUnit(nodePath, binPath, undefined, process.env, launcher), 'utf-8');
     console.log(dim(`  已写入 ${paths.file}`));
 
     run('systemctl', ['--user', 'daemon-reload']);
@@ -379,7 +471,7 @@ function install() {
 
   if (plat === 'launchd') {
     mkdirSync(join(homedir(), '.vibe-usage'), { recursive: true });
-    writeFileSync(paths.file, generateLaunchdPlist(nodePath, binPath), 'utf-8');
+    writeFileSync(paths.file, generateLaunchdPlist(nodePath, binPath, undefined, process.env, launcher), 'utf-8');
     console.log(dim(`  已写入 ${paths.file}`));
 
     const result = run('launchctl', ['load', paths.file]);
@@ -402,7 +494,7 @@ function install() {
       'wscript.exe',
     );
 
-    writeFileSync(paths.cmd, generateWindowsTaskCmd(nodePath, binPath), 'utf-8');
+    writeFileSync(paths.cmd, generateWindowsTaskCmd(nodePath, binPath, undefined, process.env, launcher), 'utf-8');
     writeFileSync(paths.vbs, generateWindowsTaskVbs(paths.cmd), 'utf-8');
     writeFileSync(paths.file, generateWindowsTaskXml(userId, wscriptPath, paths.vbs), 'utf-8');
     console.log(dim(`  已写入 ${paths.file}`));
@@ -421,8 +513,11 @@ function install() {
   }
 
   console.log();
-  console.log(success('Daemon 已安装，用量数据将每 30 分钟自动同步。'));
-  console.log(dim('  运行 `vibe-usage daemon status` 查看状态。'));
+  console.log(success('已开启后台自动同步（每 30 分钟一次，登录自启）。'));
+  if (launcher?.mode === 'npx') {
+    console.log(dim('  服务通过 npx 启动，每次登录自动使用最新版。'));
+  }
+  console.log(dim('  关闭: npx @vibe-cafe/vibe-usage daemon uninstall'));
 }
 
 function uninstall() {
@@ -484,12 +579,19 @@ function status() {
 
   const paths = getServicePaths(plat);
 
+  const printMode = () => {
+    const mode = describeInstalledMode(plat, paths);
+    if (mode === 'npx') console.log(dim(`  运行方式: npx ${PACKAGE_SPEC}（每次登录自动更新）`));
+    else if (mode === 'pinned') console.log(dim('  运行方式: 固定路径（升级后需 daemon uninstall 再重跑一条命令）'));
+  };
+
   if (plat === 'taskscheduler') {
     if (!taskExists()) {
       console.log(dim('未安装 daemon 服务。'));
       console.log(dim('  运行 `vibe-usage daemon install` 安装。'));
       return;
     }
+    printMode();
     const invocation = readTaskInvocation(paths);
     const processExpression = windowsDaemonProcessExpression(invocation);
     const scriptLines = [
@@ -546,6 +648,7 @@ function status() {
     console.log(dim('  运行 `vibe-usage daemon install` 安装。'));
     return;
   }
+  printMode();
 
   if (plat === 'systemd') {
     const result = run('systemctl', ['--user', 'status', `${SERVICE_NAME}.service`]);

package/src/daemon.js

@@ -16,7 +16,7 @@ function sleep(ms) {
 export async function runDaemon({ codexExtraHome } = {}) {
   const config = loadConfig();
   if (!config?.apiKey) {
-    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage init`。'));
+    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage`。'));
     process.exit(1);
   }
 

package/src/index.js

@@ -8,7 +8,7 @@ import {
   normalizeExtraRoot,
   validateExtraRoot,
 } from './extra-roots.js';
-import { dim as dimText, failure, smallHeader, warn } from './output.js';
+import { dim as dimText, failure, hint, smallHeader, warn } from './output.js';
 import { fetchAccount } from './api.js';
 
 function printSmallHeader() {
@@ -23,7 +23,7 @@ async function showStatus() {
 
   if (!config?.apiKey) {
     console.log('  Config: not configured');
-    console.log(`  Run \`npx @vibe-cafe/vibe-usage init\` to set up.\n`);
+    console.log(`  Run \`npx @vibe-cafe/vibe-usage\` to set up.\n`);
   } else {
     console.log(`  Config: ${getConfigPath()}`);
     console.log(`  API key: ${config.apiKey.slice(0, 8)}...`);
@@ -213,6 +213,69 @@ function extractOption(args, name) {
   return { args: [...args.slice(0, idx), ...args.slice(idx + 2)], value };
 }
 
+// Boolean global flag: present anywhere in argv → true, removed from args.
+function extractFlag(args, name) {
+  const flag = `--${name}`;
+  const idx = args.findIndex(a => a === flag);
+  if (idx === -1) return { args, value: false };
+  return { args: [...args.slice(0, idx), ...args.slice(idx + 1)], value: true };
+}
+
+const BARE = 'npx @vibe-cafe/vibe-usage';
+
+// The one command we advertise. Everything else stays supported (see
+// `help --all`) but the default help must not read like a matrix.
+const SHORT_HELP = `
+  vibe-usage - Vibe Usage Tracker by VibeCafé
+
+  用法:
+    ${BARE}
+        首次运行: 浏览器登录 → 同步 → 自动开启后台同步(每 30 分钟一次)
+        之后运行: 手动同步一次
+
+  常用:
+    ${BARE} daemon status      查看后台同步
+    ${BARE} daemon uninstall   关闭后台同步
+    ${BARE} summary [--days N] 最近 N 天用量(默认 7)
+    ${BARE} help --all         全部命令与选项
+
+  旧命令(sync、init、daemon install …)仍可用，见 help --all。
+`;
+
+const FULL_HELP = `
+  vibe-usage - Vibe Usage Tracker by VibeCafé
+
+  Usage:
+    ${BARE}              Init (first run, browser login, then background sync) or sync
+    ${BARE} --no-daemon  Same, but do not install the background service on first run
+    ${BARE} init         Set up via browser login (default)
+    ${BARE} init --manual-key <vbu_...>   Skip browser, use a pre-issued key (CI/headless)
+    ${BARE} sync         Manually sync usage data
+    ${BARE} sync --extra-codex-home <path>  Use another Codex Home for this run
+    ${BARE} summary       Print last 7 days as markdown (cost/tokens/model/project)
+    ${BARE} summary --days N   Same, but over the last N days (1-90)
+    ${BARE} daemon       Continuous sync (every 30m, foreground)
+    ${BARE} daemon install    Install background service (systemd/launchd/Task Scheduler)
+    ${BARE} daemon uninstall  Remove background service
+    ${BARE} daemon status     Show background service status
+    ${BARE} daemon stop       Stop background service
+    ${BARE} daemon restart    Restart background service
+    ${BARE} reset        Delete all data and re-upload
+    ${BARE} reset --local  Delete data for this host only and re-upload (--host is a legacy alias)
+    ${BARE} skill         Install skill for AI coding tools
+    ${BARE} skill --remove  Remove installed skills
+    ${BARE} status       Show config and detected tools
+    ${BARE} config show  Show full config as JSON
+    ${BARE} config get <key>   Get a config value
+    ${BARE} config set <key> <value>  Set a config value
+    ${BARE} config set codexExtraHome <path>  Persist another Codex Home
+    ${BARE} config add-root <tool> <path>  Add a Codex, Grok, Antigravity, or Pi data root
+    ${BARE} config remove-root <tool> <path>  Remove an added data root
+    ${BARE} config roots  Show added data roots as JSON
+    ${BARE} help         Show the short help
+    ${BARE} help --all   Show this full list
+`;
+
 export async function run(rawArgs) {
   // --key and --manual-key both mean "skip device flow, take this vbu_ key".
   // --manual-key is the documented name; --key is kept as a legacy alias so
@@ -222,7 +285,10 @@ export async function run(rawArgs) {
   ({ args: stripped, value: apiKey } = extractOption(rawArgs, 'manual-key'));
   if (apiKey === undefined) {
     ({ args: stripped, value: apiKey } = extractOption(stripped, 'key'));
+    if (apiKey !== undefined) hint('--key 已改名 --manual-key，旧写法仍可用');
   }
+  let noDaemon;
+  ({ args: stripped, value: noDaemon } = extractFlag(stripped, 'no-daemon'));
   let codexExtraHome;
   ({ args: stripped, value: codexExtraHome } = extractOption(stripped, 'extra-codex-home'));
   if (codexExtraHome !== undefined) {
@@ -239,14 +305,19 @@ export async function run(rawArgs) {
 
   switch (command) {
     case 'init': {
+      // Re-running init on a configured machine is the account re-bind path;
+      // only a genuine first setup gets nudged toward the bare command.
+      const firstSetup = !loadConfig()?.apiKey;
       const { runInit } = await import('./init.js');
-      await runInit({ apiKey, codexExtraHome });
+      await runInit({ apiKey, codexExtraHome, noDaemon });
+      if (firstSetup) hint(`以后直接运行 ${BARE} 即可：首次登录，之后同步`);
       break;
     }
     case 'sync': {
       printSmallHeader();
       const { runSync } = await import('./sync.js');
       await runSync({ codexExtraHome });
+      hint(`以后直接运行 ${BARE} 就是同步，不用再加 sync`);
       break;
     }
     case 'summary': {
@@ -256,15 +327,18 @@ export async function run(rawArgs) {
     }
     case 'reset': {
       printSmallHeader();
+      if (args.includes('--host')) hint('reset --host 已改名 reset --local，旧写法仍可用');
       const { runReset } = await import('./reset.js');
       await runReset(args.slice(1));
       break;
     }
     case 'daemon':
     case '--daemon': {
+      if (command === '--daemon') hint('--daemon 已改名 daemon，旧写法仍可用');
       const sub = args[1];
       if (sub === undefined) {
         // Foreground daemon loop — no header, just start syncing
+        hint(`首次运行 ${BARE} 会自动开启后台同步，不用手动跑 daemon`);
         const { runDaemon } = await import('./daemon.js');
         await runDaemon({ codexExtraHome });
       } else {
@@ -278,6 +352,7 @@ export async function run(rawArgs) {
         printSmallHeader();
         const { manageDaemon } = await import('./daemon-service.js');
         await manageDaemon(sub);
+        if (sub === 'install') hint(`首次运行 ${BARE} 会自动开启后台同步，不用单独装`);
       }
       break;
     }
@@ -298,37 +373,7 @@ export async function run(rawArgs) {
     case 'help':
     case '--help':
     case '-h': {
-      console.log(`
-  vibe-usage - Vibe Usage Tracker by VibeCafé
-
-  Usage:
-    npx @vibe-cafe/vibe-usage              Init (first run, browser login) or sync
-    npx @vibe-cafe/vibe-usage init         Set up via browser login (default)
-    npx @vibe-cafe/vibe-usage init --manual-key <vbu_...>   Skip browser, use a pre-issued key (CI/headless)
-    npx @vibe-cafe/vibe-usage sync         Manually sync usage data
-    npx @vibe-cafe/vibe-usage sync --extra-codex-home <path>  Use another Codex Home for this run
-    npx @vibe-cafe/vibe-usage summary       Print last 7 days as markdown (cost/tokens/model/project)
-    npx @vibe-cafe/vibe-usage summary --days N   Same, but over the last N days (1-90)
-    npx @vibe-cafe/vibe-usage daemon       Continuous sync (every 30m, foreground)
-    npx @vibe-cafe/vibe-usage daemon install    Install background service (systemd/launchd/Task Scheduler)
-    npx @vibe-cafe/vibe-usage daemon uninstall  Remove background service
-    npx @vibe-cafe/vibe-usage daemon status     Show background service status
-    npx @vibe-cafe/vibe-usage daemon stop       Stop background service
-    npx @vibe-cafe/vibe-usage daemon restart    Restart background service
-    npx @vibe-cafe/vibe-usage reset        Delete all data and re-upload
-    npx @vibe-cafe/vibe-usage reset --local  Delete data for this host only and re-upload (--host is a legacy alias)
-    npx @vibe-cafe/vibe-usage skill         Install skill for AI coding tools
-    npx @vibe-cafe/vibe-usage skill --remove  Remove installed skills
-    npx @vibe-cafe/vibe-usage status       Show config and detected tools
-    npx @vibe-cafe/vibe-usage config show  Show full config as JSON
-    npx @vibe-cafe/vibe-usage config get <key>   Get a config value
-    npx @vibe-cafe/vibe-usage config set <key> <value>  Set a config value
-    npx @vibe-cafe/vibe-usage config set codexExtraHome <path>  Persist another Codex Home
-    npx @vibe-cafe/vibe-usage config add-root <tool> <path>  Add a Codex, Grok, Antigravity, or Pi data root
-    npx @vibe-cafe/vibe-usage config remove-root <tool> <path>  Remove an added data root
-    npx @vibe-cafe/vibe-usage config roots  Show added data roots as JSON
-    npx @vibe-cafe/vibe-usage help         Show this help
-`);
+      console.log(args.includes('--all') ? FULL_HELP : SHORT_HELP);
       break;
     }
     case undefined: {
@@ -338,7 +383,7 @@ export async function run(rawArgs) {
       if (!config?.apiKey || apiKey) {
         // First run OR user passed --key for a one-shot setup — init.js prints the big header
         const { runInit } = await import('./init.js');
-        await runInit({ apiKey, codexExtraHome });
+        await runInit({ apiKey, codexExtraHome, noDaemon });
       } else {
         // Already configured: small header + sync
         printSmallHeader();

package/src/init.js

@@ -6,6 +6,7 @@ import { fetchAccount, ingest, requestDeviceCode, pollDeviceCode } from './api.j
 import { runSync } from './sync.js';
 import { detectInstalledTools } from './tools.js';
 import { bigHeader, success, failure, warn, arrow, link, dim, divider } from './output.js';
+import { manageDaemon, isDaemonInstalled, isDaemonPlatform } from './daemon-service.js';
 
 const CLIENT_NAME = 'vibe-usage CLI';
 
@@ -26,12 +27,8 @@ function openBrowser(url) {
   execFile(cmd, [url], () => {});
 }
 
-function isDaemonPlatform() {
-  return process.platform === 'linux' || process.platform === 'darwin' || process.platform === 'win32';
-}
-
 export async function runInit(options = {}) {
-  const { apiKey: providedKey, codexExtraHome } = options;
+  const { apiKey: providedKey, codexExtraHome, noDaemon = false } = options;
 
   console.log(bigHeader());
 
@@ -108,22 +105,21 @@ export async function runInit(options = {}) {
 
   await runSync({ codexExtraHome });
 
-  if (isDaemonPlatform()) {
-    if (process.stdin.isTTY) {
-      console.log();
-      const answer = await prompt(`开启后台自动同步？${dim('(推荐)')} [Y/n] `);
-      const normalized = answer.toLowerCase();
-      if (normalized === '' || normalized === 'y' || normalized === 'yes') {
-        const { manageDaemon } = await import('./daemon-service.js');
-        await manageDaemon('install');
-      } else {
-        console.log();
-        console.log(dim('随时运行 `npx @vibe-cafe/vibe-usage daemon install` 开启后台同步。'));
-      }
-    } else {
-      console.log();
-      console.log(dim('提示: 运行 `npx @vibe-cafe/vibe-usage daemon install` 开启后台自动同步。'));
-    }
+  // Background sync is the default (maintainer decision 2026-09-09): one
+  // command should leave the machine fully set up. `--no-daemon` opts out;
+  // a non-interactive run (CI, headless --manual-key) never installs a
+  // service on a machine nobody is looking at.
+  console.log();
+  if (noDaemon) {
+    console.log(dim('已按 --no-daemon 跳过后台同步。随时运行 `npx @vibe-cafe/vibe-usage daemon install` 开启。'));
+  } else if (!isDaemonPlatform()) {
+    console.log(dim('当前平台不支持后台同步，之后手动运行 `npx @vibe-cafe/vibe-usage` 即可同步。'));
+  } else if (isDaemonInstalled()) {
+    console.log(success('后台自动同步已在运行。'));
+  } else if (process.stdin.isTTY) {
+    await manageDaemon('install');
+  } else {
+    console.log(dim('非交互环境未开启后台同步；运行 `npx @vibe-cafe/vibe-usage daemon install` 开启。'));
   }
 }
 

package/src/output.js

@@ -41,6 +41,17 @@ export const arrow = (msg) => `${cyan('→')} ${msg}`;
 
 export const divider = () => dim('─'.repeat(48));
 
+/**
+ * One dim advisory line pointing at the simpler way to do what the user just
+ * did. Printed only when a human is watching: the Mac and Windows apps drive
+ * `sync` through a pipe and read stdout as the result / error text, so an
+ * extra line must never reach them. VIBE_USAGE_FORCE_HINTS=1 is for tests.
+ */
+export function hint(msg) {
+  if (!process.stdout.isTTY && process.env.VIBE_USAGE_FORCE_HINTS !== '1') return;
+  console.log(dim(`提示: ${msg}`));
+}
+
 /** Print a blank line. */
 export const nl = () => console.log();
 

package/src/reset.js

@@ -30,7 +30,7 @@ export async function runReset(args = [], deps = {}) {
   const hostOnly = args.includes('--local') || args.includes('--host');
   const config = loadConfig();
   if (!config?.apiKey) {
-    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage init`。'));
+    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage`。'));
     process.exit(1);
   }
 

package/src/summary.js

@@ -6,7 +6,7 @@ export async function runSummary(args = []) {
   const days = parseDays(args);
   const config = loadConfig();
   if (!config?.apiKey) {
-    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage init`。'));
+    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage`。'));
     process.exit(1);
   }
 
@@ -42,7 +42,7 @@ function render(data, days, apiUrl) {
   const dashboard = `${apiUrl}/usage`;
 
   if (buckets.length === 0) {
-    return `# Vibe Usage Summary (Last ${days} ${days === 1 ? 'day' : 'days'})\n\n暂无数据。运行 \`npx @vibe-cafe/vibe-usage sync\` 上传本地 token 记录。\n\n详情: ${dashboard}\n`;
+    return `# Vibe Usage Summary (Last ${days} ${days === 1 ? 'day' : 'days'})\n\n暂无数据。运行 \`npx @vibe-cafe/vibe-usage\` 上传本地 token 记录。\n\n详情: ${dashboard}\n`;
   }
 
   let totalCost = 0;

package/src/sync.js

@@ -86,7 +86,7 @@ export async function runSync({
 } = {}) {
   const config = loadConfig();
   if (!config?.apiKey) {
-    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage init`。'));
+    console.error(failure('尚未配置，请先运行 `npx @vibe-cafe/vibe-usage`。'));
     if (throws) throw new Error('NOT_CONFIGURED');
     process.exit(1);
   }