#6273 feat(cli): branded help and interactive command browser with guided flag prompts

Summary

• superset --help becomes a branded, colored help screen: tagline, copy-paste Examples, commands grouped into curated sections (Workspaces & agents / Tasks & automations / Hosts & projects / Account), and a Docs + Tip footer. Colors auto-disable on non-TTY or NO_COLOR.
• Bare superset on a TTY opens an interactive command browser: arrow-key navigation over the whole command tree, per-command flag docs, and one-key execution. Commands with required inputs get a guided form — text inputs, enum selectors (↑↓), yes/no — ending in a "Ready:" screen that shows the exact assembled command before running it.
• Agents and CI are untouched: the browser only opens when stdin+stdout are TTYs and isAgentMode() is false (same env-var detection that drives auto-JSON), so any environment that gets JSON output still gets static help.

Why / Context

The CLI is bundled with the desktop app and on PATH in every Superset terminal, but discovering what it can do requires reading docs. This makes bare superset a self-guided tour: browse → read flags → fill in required inputs → run — and the confirm screen teaches the real command syntax as a side effect. Companion to the built-in "Superset CLI" preset (#6270), which opens a terminal in the app; this is what users see when they get there.

How It Works

• cli-framework/src/help.ts: new optional HelpBranding (tagline, sections, examples, docsUrl, tip) + ANSI paint helper; generateRootHelp renders the branded layout when branding is configured. Group/command help unchanged.
• cli-framework/src/interactive-help.ts (new): zero-dependency raw-mode browser — arrow-key escape-sequence parsing, in-place frame repainting, tree navigation, collectRequiredFields() (required args/flags, positionals first, required-with-default excluded), form state machine (text/enum/boolean), buildRunArgs() assembling argv.
• cli-framework/src/runner.ts: bare-args + TTY + !isAgentMode() gate; on "run", re-enters execute() with the assembled argv so middleware/auth/output behave exactly as if typed.
• config.ts/dev.ts/build.ts: plumb help from cli.config.ts into run() (dev mode and compiled binary).
• packages/cli/cli.config.ts: the Superset-specific branding content. The framework stays generic — any CLI built on it opts in with its own help: block.

Zero new dependencies (no ink/clack in the framework); works in the compiled binary.

Manual QA (dev CLI in Ghostty + Superset terminal via CDP, screenshots captured)

• bun run dev --help renders branded static help; piping strips colors
• Bare bun run dev in a TTY opens the browser; agent-env shells still get static help
• Navigation: groups drill in, breadcrumbs update, ← backs out, q quits, raw mode restored
• Leaf with no required inputs (status): "enter run it now" executes through normal middleware (auth error surfaces normally against a dev API without login)
• Leaf with required inputs (feedback submit): enum selector for --type, text input for --title, confirm screen shows superset feedback submit --type feature --title "…", ← edits last field, esc cancels
• Windows terminal key handling (untested — known gap)

Testing

• bun test packages/cli-framework/src/interactive-help.test.ts (7 tests: required-field collection incl. enum/default/positional ordering, argv assembly, boolean flags, display quoting)
• bun turbo run typecheck --filter=@superset/cli-framework --filter=@superset/cli
• bun run lint

Known Limitations / Follow-ups

• Guided form covers required inputs only; optional flags still typed by hand
• No pick-lists from live data yet (e.g. selecting --project from projects list --json) — the natural next step
• No type-to-filter search in the browser; Windows key handling unverified

---

Summary by cubic

Adds a branded help screen and an interactive command browser to the superset CLI for easier command discovery and execution. Fixes an early-abort case and ensures the terminal is always restored; CI/agents still get static help.

• New Features

  • Branded root help: tagline, curated sections, copy‑paste examples, and docs/tip footer; colors auto‑disable on non‑TTY or NO_COLOR.
  • Bare superset in a TTY opens a browser with arrow‑key navigation, per‑command flag docs, and one‑key run. Guided form gathers required inputs (text, enum picker, yes/no, variadic), then shows a quoted “Ready” command; booleans support --no-<flag> when false.
  • TTY + !isAgentMode() gate; execution re‑enters the normal runner with the assembled argv so middleware/auth/output behave the same.

• Bug Fixes

  • Always restore terminal state (raw mode and cursor) on quit, errors, signal aborts, and when the abort signal was already fired before startup.
  • Better key handling (arrows/backspace/esc/ctrl‑c) and variadic input splitting for flags and positionals.

Summary by CodeRabbit

• New Features

  • Added an interactive help browser for navigating commands and entering required options.
  • Added customizable help branding, including taglines, command sections, examples, documentation links, and tips.
  • Improved root help output with styled headers, grouped commands, usage details, and examples.
  • Added branded help content and practical command examples to the CLI.
  • Bare interactive terminal launches can now guide users through command selection and required inputs.

• Tests

  • Added coverage for interactive command selection, argument handling, flags, defaults, and display formatting.