Refactor CLI

[AbhinRustagi]

What

Restructure @openuidev/cli so a new command is a folder + one registry line. Same four commands, still Commander.

Placement: one command owns it → that command’s folder. Two or more owners (or a later command will) → src/lib/.

packages/openui-cli/src/
  index.ts                         # shebang, runProgram()
  program.ts                       # globals, telemetry init, process error catch
  commands/
    index.ts                       # addCommand list — new command = one line
    create/
      command.ts                   # flags + help
      run.ts                       # orchestrator (resolve → env → scaffold → install)
      lib/                         # create-only: catalogs, overlays, stages, examples
    deploy/
      command.ts
      run.ts
      lib/                         # deploy-only: project env, vercel target, vercel-env
    generate/
      command.ts
      run.ts
      lib/                         # worker + delimiter (do not import worker from run)
    generate-api-key/
      command.ts
      run.ts
  lib/
    context.ts                     # cwd / argv / telemetry / verbose
    telemetry.ts                   # PostHog session; commands extend Telemetry
    errors.ts                      # CreateError, mapping, throwCommandFailure
    auth/                          # create + generate-api-key
    scaffold/                      # checkout/copy/rewrite for a future init
    env.ts                         # generic parse / upsert / remove
    checkout.ts, process-runner.ts, spinner.ts, …

Context: one CliContext (cwd, argv, telemetry, verbose) is set on the program, then passed top-down into every run* function. Commands read process state from ctx instead of reaching for globals.

Telemetry: one Telemetry class owns the PostHog session (init / capture / shutdown). Each command extends it with typed methods (CreateTelemetryClient.trackStarted(...), etc.) so event names and payloads live on the subclass, not as stringly-typed capture("cli_…") at call sites. new CreateTelemetryClient(ctx.telemetry) shares the same session.

Breaking

Removed normalizeTemplate / normalizeBackendFramework. --template and --backend-framework match catalog keys only — short names no longer resolve.

Flag	Was (also accepted)	Now
--template	cloud, self-hosted	openui-cloud, openui-self-hosted
--backend-framework	eve, none, vercel, ai-sdk, lang-graph	default, langgraph, vercel-ai-sdk, vercel-eve

--auth manual is unchanged.

Other

• --verbose is global (openui --verbose create and openui create --verbose). --no-interactive stays per-command.

Test Plan

• Verified locally
• pnpm --filter @openuidev/cli run ci
• --help for root + each command
• --verbose before and after the subcommand
• create --template cloud errors with the catalog key list

Checklist

• I linked a related issue, if applicable
• I updated docs/README when needed
• I considered backwards compatibility

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
openui-docs	Ready	Preview	Sep 18, 2026 10:02am UTC