From 4bb327992fdff19c46bd5ccad566a967c2d2876e Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Wed, 25 Mar 2026 22:59:27 -0700
Subject: [PATCH] fix(cli): improve --help documentation and add --yes/--check
 to upgrade
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- upgrade: add --yes and --check flags to skip interactive prompt
- benchmark: clarify description — preset fps/quality/worker configs
- browser: describe each subcommand (ensure/path/clear) in help
- docs: list available topics inline in --help output

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/cli/src/commands/benchmark.ts |  2 +-
 packages/cli/src/commands/browser.ts   |  3 ++-
 packages/cli/src/commands/docs.ts      |  8 +++++++-
 packages/cli/src/commands/upgrade.ts   | 28 ++++++++++++++++++--------
 4 files changed, 30 insertions(+), 11 deletions(-)

diff --git a/packages/cli/src/commands/benchmark.ts b/packages/cli/src/commands/benchmark.ts
index beb198fc2d..c6a9c7b4a3 100644
--- a/packages/cli/src/commands/benchmark.ts
+++ b/packages/cli/src/commands/benchmark.ts
@@ -38,7 +38,7 @@ const DEFAULT_CONFIGS: BenchmarkConfig[] = [
 export default defineCommand({
   meta: {
     name: "benchmark",
-    description: "Run multiple render configurations and compare results",
+    description: "Render with preset fps/quality/worker configs and compare speed and file size",
   },
   args: {
     dir: { type: "positional", description: "Project directory", required: false },
diff --git a/packages/cli/src/commands/browser.ts b/packages/cli/src/commands/browser.ts
index 3144abfb8a..f5e390ad56 100644
--- a/packages/cli/src/commands/browser.ts
+++ b/packages/cli/src/commands/browser.ts
@@ -90,7 +90,8 @@ export default defineCommand({
   args: {
     subcommand: {
       type: "positional",
-      description: "Subcommand: ensure, path, clear",
+      description:
+        "ensure = find or download Chrome, path = print executable path, clear = remove cached download",
       required: false,
     },
   },
diff --git a/packages/cli/src/commands/docs.ts b/packages/cli/src/commands/docs.ts
index 3c11fe9bcd..1a6c7bafa4 100644
--- a/packages/cli/src/commands/docs.ts
+++ b/packages/cli/src/commands/docs.ts
@@ -84,10 +84,16 @@ function renderMarkdown(content: string): void {
   }
 }
 
+const TOPIC_NAMES = Object.keys(TOPICS).join(", ");
+
 export default defineCommand({
   meta: { name: "docs", description: "View inline documentation in the terminal" },
   args: {
-    topic: { type: "positional", description: "Topic to view", required: false },
+    topic: {
+      type: "positional",
+      description: `Topic: ${TOPIC_NAMES}. Omit to list all.`,
+      required: false,
+    },
   },
   async run({ args }) {
     const topic = args.topic;
diff --git a/packages/cli/src/commands/upgrade.ts b/packages/cli/src/commands/upgrade.ts
index 50989001ab..de3b9f5722 100644
--- a/packages/cli/src/commands/upgrade.ts
+++ b/packages/cli/src/commands/upgrade.ts
@@ -5,8 +5,13 @@ import { VERSION } from "../version.js";
 
 export default defineCommand({
   meta: { name: "upgrade", description: "Check for updates and show upgrade instructions" },
-  args: {},
-  async run() {
+  args: {
+    yes: { type: "boolean", alias: "y", description: "Show upgrade commands without prompting" },
+    check: { type: "boolean", description: "Check for updates and exit (no prompt)" },
+  },
+  async run({ args }) {
+    const autoYes = args.yes === true;
+    const checkOnly = args.check === true;
     clack.intro(c.bold("hyperframes upgrade"));
 
     const s = clack.spinner();
@@ -41,15 +46,22 @@ export default defineCommand({
     console.log(`   ${c.dim("Latest:")}   ${c.bold(c.accent("v" + latest))}`);
     console.log();
 
-    const shouldUpgrade = await clack.confirm({
-      message: "Upgrade now?",
-    });
-
-    if (clack.isCancel(shouldUpgrade) || !shouldUpgrade) {
-      clack.outro(c.dim("Skipped."));
+    if (checkOnly) {
+      clack.outro(c.accent("Update available: v" + latest));
       return;
     }
 
+    if (!autoYes) {
+      const shouldUpgrade = await clack.confirm({
+        message: "Upgrade now?",
+      });
+
+      if (clack.isCancel(shouldUpgrade) || !shouldUpgrade) {
+        clack.outro(c.dim("Skipped."));
+        return;
+      }
+    }
+
     console.log();
     console.log(`   ${c.accent("npm install -g hyperframes@" + latest)}`);
     console.log(`   ${c.dim("or")}`);