;
+}
+
+const SUCCESS_HTML = `Signed in✓ Signed in
You can close this tab and return to your terminal.
`;
+
+const errorHtml = (msg: string) =>
+ `Sign-in failedSign-in failed
${msg}
Return to your terminal and try again.
`;
+
+/** OAuth 2.0 + PKCE via a local loopback callback. ESM-only deps load via dynamic import(). */
+export class Authenticator {
+ private readonly config: AuthConfig & { redirectUri: string; scopes: string[] };
+ private clientConfig?: Configuration;
+ private codeVerifier?: string;
+
+ constructor(config: AuthConfig) {
+ this.config = {
+ redirectUri: "http://localhost:0/cb", // 0 = any free port
+ scopes: ["openid", "profile", "email"],
+ ...config,
+ };
+ }
+
+ getClientConfig(): Configuration {
+ if (!this.clientConfig) {
+ throw new Error("Client not initialized. Call initialize() first.");
+ }
+ return this.clientConfig;
+ }
+
+ async initialize(): Promise {
+ const { discovery } = await import("openid-client");
+ this.clientConfig = await discovery(new URL(this.config.issuerUrl), this.config.clientId);
+ }
+
+ async authenticate(): Promise {
+ if (!this.clientConfig) {
+ throw new Error("Client not initialized. Call initialize() first.");
+ }
+ const { randomPKCECodeVerifier, calculatePKCECodeChallenge } = await import("openid-client");
+ this.codeVerifier = randomPKCECodeVerifier();
+ const codeChallenge = await calculatePKCECodeChallenge(this.codeVerifier);
+ return this.handleBrowserAuth(codeChallenge);
+ }
+
+ private async handleBrowserAuth(codeChallenge: string): Promise {
+ const { authorizationCodeGrant, buildAuthorizationUrl } = await import("openid-client");
+ const { default: open } = await import("open");
+
+ return new Promise((resolve, reject) => {
+ let settled = false;
+ let actualPort = 0;
+ let timerId: null | NodeJS.Timeout = null;
+ const finish = (run: () => void) => {
+ if (settled) return;
+ settled = true;
+ if (timerId) clearTimeout(timerId);
+ server.close();
+ run();
+ };
+
+ const server = http.createServer(async (req, res) => {
+ if (!req.url?.startsWith("/cb")) {
+ res.writeHead(404, { Connection: "close" });
+ res.end("Not found");
+ return;
+ }
+ try {
+ const callbackUrl = new URL(req.url, `http://localhost:${actualPort}`);
+ if (!this.clientConfig || !this.codeVerifier) {
+ throw new Error("Client not properly initialized");
+ }
+ const tokens = await authorizationCodeGrant(this.clientConfig, callbackUrl, {
+ pkceCodeVerifier: this.codeVerifier,
+ });
+ let userInfo: Record | undefined;
+ try {
+ const claims = tokens.claims();
+ if (claims) userInfo = claims as Record;
+ } catch {
+ /* no id_token claims */
+ }
+ res.writeHead(200, { "Content-Type": "text/html", Connection: "close" });
+ res.end(SUCCESS_HTML);
+ finish(() =>
+ resolve({
+ accessToken: tokens.access_token ?? "",
+ refreshToken: tokens.refresh_token,
+ idToken: tokens.id_token,
+ userInfo,
+ }),
+ );
+ } catch (error) {
+ const msg = error instanceof Error ? error.message : "Unknown error";
+ res.writeHead(200, { "Content-Type": "text/html", Connection: "close" });
+ res.end(errorHtml(msg));
+ finish(() => reject(new Error(`Token exchange failed: ${msg}`)));
+ }
+ });
+
+ server.on("error", (error) => finish(() => reject(error)));
+
+ server.listen(0, async () => {
+ const address = server.address();
+ if (!address || typeof address === "string") {
+ finish(() => reject(new Error("Failed to bind a local callback port.")));
+ return;
+ }
+ actualPort = address.port;
+ const url = buildAuthorizationUrl(this.clientConfig!, {
+ redirect_uri: `http://localhost:${actualPort}/cb`,
+ scope: this.config.scopes.join(" "),
+ code_challenge: codeChallenge,
+ code_challenge_method: "S256",
+ prompt: "consent",
+ }).toString();
+
+ console.info("\n🌐 Opening your browser to sign in to Thesys…");
+ console.info(` If it doesn't open, visit:\n ${url}\n`);
+ try {
+ await open(url);
+ } catch {
+ /* user opens the URL manually */
+ }
+ console.info("⏳ Waiting for you to finish signing in…");
+ });
+
+ timerId = setTimeout(
+ () => finish(() => reject(new Error("Sign-in timed out after 5 minutes."))),
+ 5 * 60 * 1000,
+ );
+ });
+ }
+}
diff --git a/packages/openui-cli/src/auth/mint.ts b/packages/openui-cli/src/auth/mint.ts
new file mode 100644
index 000000000..bec7d2f19
--- /dev/null
+++ b/packages/openui-cli/src/auth/mint.ts
@@ -0,0 +1,92 @@
+import { Authenticator } from "./authenticator";
+
+// Thesys console OAuth + key mint (same flow as create-c1-app). The OpenUI Cloud
+// master key is the same C1-flavored org API key (usageType "C1").
+const THESYS_API_URL = "https://api.app.thesys.dev";
+const THESYS_ISSUER_URL = "https://api.app.thesys.dev/oidc";
+const THESYS_CLIENT_ID = "create-c1-app"; // public PKCE client (no secret)
+export const THESYS_KEYS_URL = "https://console.thesys.dev/keys";
+
+export type CloudAuthMethod = "oauth" | "manual" | "skip";
+/** How the cloud key was obtained (for telemetry) — auth method + the `--api-key` flag case. */
+export type ResolvedAuthMethod = CloudAuthMethod | "apikey-flag";
+
+/** Sign in via the browser and mint an OpenUI Cloud API key for the user's org. */
+export async function mintCloudApiKey(projectName: string): Promise {
+ const auth = new Authenticator({ issuerUrl: THESYS_ISSUER_URL, clientId: THESYS_CLIENT_ID });
+ await auth.initialize();
+ const { accessToken, userInfo } = await auth.authenticate();
+
+ const { fetchUserInfo } = await import("openid-client");
+ const profile = await fetchUserInfo(
+ auth.getClientConfig(),
+ accessToken,
+ (userInfo?.["sub"] as string | undefined) ?? "",
+ );
+ const orgId = (profile["org_claims"] as { orgId: string }[] | undefined)?.[0]?.orgId;
+ if (!orgId) {
+ throw new Error(`No organization found for your account. Create a key at ${THESYS_KEYS_URL}.`);
+ }
+
+ console.info("🔑 Creating an OpenUI Cloud API key…");
+ const res = await fetch(`${THESYS_API_URL}/application/application.createApiKeyWithOidc`, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ Accept: "application/json",
+ },
+ body: JSON.stringify({ name: projectName || "OpenUI Cloud App", orgId, usageType: "C1" }),
+ });
+ if (!res.ok) {
+ throw new Error(`Failed to create API key (HTTP ${res.status}): ${await res.text()}`);
+ }
+ const data = (await res.json()) as { apiKey?: string };
+ if (!data.apiKey) throw new Error("The server did not return an API key.");
+ return data.apiKey;
+}
+
+/**
+ * Resolve a cloud API key by the chosen method: an explicitly provided key, a
+ * browser OAuth mint, a manual paste, or skip (null → leave the .env slot empty).
+ */
+export async function resolveCloudApiKey(opts: {
+ apiKey?: string;
+ auth?: CloudAuthMethod;
+ projectName: string;
+ interactive: boolean;
+}): Promise<{ key: string | null; method: ResolvedAuthMethod }> {
+ const provided = opts.apiKey?.trim();
+ if (provided) return { key: provided, method: "apikey-flag" };
+
+ let method = opts.auth;
+ if (!method) {
+ if (!opts.interactive) {
+ throw new Error(
+ `An API key is required in non-interactive mode. Pass --api-key ` +
+ `(get one at ${THESYS_KEYS_URL}).`,
+ );
+ }
+ const { select } = await import("@inquirer/prompts");
+ method = (await select({
+ message: "Connect to OpenUI Cloud:",
+ choices: [
+ { name: "Sign in with Thesys (opens a browser, mints a key)", value: "oauth" },
+ { name: "Paste an existing API key", value: "manual" },
+ { name: "Skip — add THESYS_API_KEY to .env later", value: "skip" },
+ ],
+ })) as CloudAuthMethod;
+ }
+
+ if (method === "skip") return { key: null, method: "skip" };
+
+ if (method === "manual") {
+ const { password } = await import("@inquirer/prompts");
+ const key = (
+ await password({ message: "Paste your OpenUI Cloud API key:", mask: true })
+ ).trim();
+ return { key: key || null, method: "manual" };
+ }
+
+ return { key: await mintCloudApiKey(opts.projectName), method: "oauth" };
+}
diff --git a/packages/openui-cli/src/commands/create-app.ts b/packages/openui-cli/src/commands/create-app.ts
new file mode 100644
index 000000000..86726677a
--- /dev/null
+++ b/packages/openui-cli/src/commands/create-app.ts
@@ -0,0 +1,240 @@
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { resolveCloudApiKey, THESYS_KEYS_URL, type CloudAuthMethod } from "../auth/mint";
+import { detectPackageManager } from "../lib/detect-package-manager";
+import { runSkillInstall, shouldInstallSkill } from "../lib/install-skill";
+import { resolveArgs } from "../lib/resolve-args";
+import { CreateError, telemetry } from "../lib/telemetry";
+
+export type TemplateName = "openui-chat" | "openui-cloud";
+
+export interface CreateAppOptions {
+ name?: string;
+ template?: TemplateName;
+ skill?: boolean;
+ noInteractive?: boolean;
+ noInstall?: boolean;
+ // cloud-only
+ apiKey?: string;
+ auth?: CloudAuthMethod;
+}
+
+function shouldCopyTemplatePath(templateDir: string, src: string): boolean {
+ const rel = path.relative(templateDir, src);
+ if (!rel) return true;
+ const top = rel.split(path.sep)[0] ?? "";
+ // never copy install/build artifacts that may sit in a template dir
+ return !["node_modules", ".next", ".turbo", "dist"].includes(top);
+}
+
+export async function runCreateApp(options: CreateAppOptions): Promise {
+ const interactive = !options.noInteractive;
+ const t0 = Date.now();
+ telemetry.register({ is_interactive: interactive });
+
+ const args = await resolveArgs(
+ {
+ name: options.name
+ ? { value: options.name }
+ : { prompt: { type: "input", message: "Project name?" }, required: true },
+ template: options.template
+ ? { value: options.template }
+ : {
+ prompt: {
+ type: "select",
+ message: "Which template?",
+ choices: [
+ { value: "openui-chat", name: "OpenUI Chat — bring your own model key (OpenAI)" },
+ {
+ value: "openui-cloud",
+ name: "OpenUI Cloud — managed conversations, artifacts & streaming",
+ },
+ ],
+ },
+ required: true,
+ },
+ },
+ interactive,
+ );
+
+ const { name, template } = args as { name: string; template: TemplateName };
+ telemetry.register({ template });
+ telemetry.capture("cli_create_started", { interactive });
+ telemetry.capture("cli_template_selected", { template });
+
+ const targetDir = path.resolve(process.cwd(), name);
+ if (fs.existsSync(targetDir)) {
+ throw new CreateError("dir_exists", `Directory "${name}" already exists.`);
+ }
+
+ const runner = detectPackageManager();
+ telemetry.register({ package_manager: runner });
+ const templateDir = path.join(__dirname, "..", "templates", template);
+ if (!fs.existsSync(templateDir)) {
+ throw new CreateError(
+ "template_missing",
+ `Template "${template}" not found. Rebuild the CLI with \`pnpm build\`.`,
+ );
+ }
+
+ console.info(`\nScaffolding ${template} into "${name}"...\n`);
+ fs.cpSync(templateDir, targetDir, {
+ recursive: true,
+ filter: (src) => shouldCopyTemplatePath(templateDir, src),
+ });
+
+ // package.json: set the project name and de-vendor monorepo-local deps
+ // (workspace:* / file: / catalog:) to the published "latest". link: deps are
+ // rewritten to an absolute file: path so locally-linked packages (e.g.
+ // @openuidev/thesys) keep resolving against the developer's checkout under any
+ // package manager — npm rejects link:, and ~ isn't expanded. Temporary, until
+ // these packages are published.
+ const pkgPath = path.join(targetDir, "package.json");
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
+ name: string;
+ dependencies?: Record;
+ devDependencies?: Record;
+ };
+ pkg.name = name;
+ for (const section of ["dependencies", "devDependencies"] as const) {
+ const deps = pkg[section];
+ if (!deps) continue;
+ for (const key of Object.keys(deps)) {
+ const v = deps[key];
+ if (!v) continue;
+ if (v.startsWith("link:")) {
+ const target = v.slice("link:".length);
+ const abs = target.startsWith("~")
+ ? path.join(os.homedir(), target.slice(1))
+ : path.resolve(target);
+ deps[key] = `file:${abs}`;
+ continue;
+ }
+ // workspace:/file:/catalog: are monorepo-only protocols npm/yarn/bun
+ // can't resolve standalone — pin them to the published "latest".
+ if (/^(workspace:|file:|catalog:)/.test(v)) deps[key] = "latest";
+ }
+ }
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+
+ const installCmd =
+ runner === "pnpm dlx"
+ ? "pnpm install"
+ : runner === "yarn dlx"
+ ? "yarn"
+ : runner === "bunx"
+ ? "bun install"
+ : "npm install";
+
+ if (options.noInstall) {
+ console.info(`Skipping dependency install (--no-install). Run \`${installCmd}\` later.\n`);
+ } else {
+ console.info(`Installing dependencies with: ${installCmd}\n`);
+ try {
+ execSync(installCmd, { stdio: "inherit", cwd: targetDir });
+ } catch {
+ throw new CreateError("install_deps", "dependency install failed");
+ }
+ }
+
+ const installSkill = await shouldInstallSkill(options.skill, interactive);
+ telemetry.capture("cli_skill_installed", { installed: installSkill });
+ if (installSkill) runSkillInstall(targetDir);
+
+ const envWritten =
+ template === "openui-cloud"
+ ? await writeCloudEnv(targetDir, name, options, interactive)
+ : await writeChatEnv(targetDir, interactive);
+
+ const devCmd =
+ runner === "pnpm dlx"
+ ? "pnpm"
+ : runner === "yarn dlx"
+ ? "yarn"
+ : runner === "bunx"
+ ? "bun"
+ : "npm";
+
+ telemetry.capture("cli_create_succeeded", {
+ template,
+ duration_ms: Date.now() - t0,
+ skill_installed: installSkill,
+ env_written: envWritten,
+ });
+ console.info(
+ getStartedMessage({ name, devCmd, template, skillInstalled: installSkill, envWritten }),
+ );
+}
+
+async function writeChatEnv(targetDir: string, interactive: boolean): Promise {
+ if (!interactive) return false;
+ const { input } = await import("@inquirer/prompts");
+ const apiKey = (
+ await input({ message: "Enter your OpenAI API key (leave blank to skip):" })
+ ).trim();
+ if (!apiKey) return false;
+ fs.writeFileSync(path.join(targetDir, ".env"), `OPENAI_API_KEY=${apiKey}\n`);
+ return true;
+}
+
+async function writeCloudEnv(
+ targetDir: string,
+ name: string,
+ options: CreateAppOptions,
+ interactive: boolean,
+): Promise {
+ let apiKey: string | null = null;
+ try {
+ const resolved = await resolveCloudApiKey({
+ apiKey: options.apiKey,
+ auth: options.auth,
+ projectName: name,
+ interactive,
+ });
+ apiKey = resolved.key;
+ telemetry.capture("cli_cloud_auth_method", {
+ method: resolved.method,
+ succeeded: apiKey != null,
+ });
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ console.error(`\n⚠ Could not obtain an API key: ${msg}`);
+ console.error(` Add THESYS_API_KEY to .env later (keys: ${THESYS_KEYS_URL}).\n`);
+ }
+ const lines = [`THESYS_API_KEY=${apiKey ?? ""}`, `DEMO_USER_ID=demo-user`];
+ fs.writeFileSync(path.join(targetDir, ".env"), lines.join("\n") + "\n");
+ return apiKey != null;
+}
+
+function getStartedMessage(o: {
+ name: string;
+ devCmd: string;
+ template: TemplateName;
+ skillInstalled: boolean;
+ envWritten: boolean;
+}): string {
+ const skillMessage = o.skillInstalled
+ ? "The OpenUI agent skill was installed.\nAI coding assistants will use it to help you build with OpenUI.\n"
+ : "";
+
+ const envNote =
+ o.template === "openui-cloud"
+ ? o.envWritten
+ ? "✅ .env created with your OpenUI Cloud API key + base URL."
+ : `⚠ .env created without a key. Add THESYS_API_KEY=… (get one at ${THESYS_KEYS_URL}).`
+ : o.envWritten
+ ? "✅ .env created with your API key."
+ : "Add your API key to .env:\nOPENAI_API_KEY=sk-your-key-here";
+
+ return `${skillMessage}
+Done!
+
+${envNote}
+
+> cd ${o.name}
+> ${o.devCmd} run dev
+`;
+}
diff --git a/packages/openui-cli/src/commands/create-chat-app.ts b/packages/openui-cli/src/commands/create-chat-app.ts
deleted file mode 100644
index 556b340e6..000000000
--- a/packages/openui-cli/src/commands/create-chat-app.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import { execSync } from "child_process";
-import * as fs from "fs";
-import * as path from "path";
-
-import { detectPackageManager } from "../lib/detect-package-manager";
-import { runSkillInstall, shouldInstallSkill } from "../lib/install-skill";
-import { resolveArgs } from "../lib/resolve-args";
-
-export interface CreateChatAppOptions {
- name?: string;
- skill?: boolean;
- noInteractive?: boolean;
-}
-
-function shouldCopyTemplatePath(templateDir: string, src: string): boolean {
- const relativePath = path.relative(templateDir, src);
-
- if (!relativePath) return true;
-
- return relativePath !== "openui-chat" && !relativePath.startsWith(`openui-chat${path.sep}`);
-}
-
-export async function runCreateChatApp(options: CreateChatAppOptions): Promise {
- const args = await resolveArgs(
- {
- name: options.name
- ? { value: options.name }
- : {
- prompt: { type: "input", message: "Project name?" },
- required: true,
- },
- },
- !options.noInteractive,
- );
-
- const { name } = args as { name: string };
- const targetDir = path.resolve(process.cwd(), name);
-
- if (fs.existsSync(targetDir)) {
- console.error(`Error: Directory "${name}" already exists.`);
- process.exit(1);
- }
-
- const runner = detectPackageManager();
-
- const templateDir = path.join(__dirname, "..", "templates", "openui-chat");
- if (!fs.existsSync(templateDir)) {
- console.error("Error: Template not found. Please rebuild the CLI with `pnpm build`.");
- process.exit(1);
- }
-
- console.info(`\nScaffolding OpenUI Chat app into "${name}"...\n`);
-
- const nestedTemplateDir = path.join(templateDir, "openui-chat");
- if (fs.existsSync(nestedTemplateDir)) {
- console.warn("Warning: Ignoring nested template directory left by a previous CLI build.");
- }
-
- fs.cpSync(templateDir, targetDir, {
- recursive: true,
- filter: (src) => shouldCopyTemplatePath(templateDir, src),
- });
-
- const pkgPath = path.join(targetDir, "package.json");
- const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
- name: string;
- dependencies?: Record;
- devDependencies?: Record;
- };
- pkg.name = name;
- for (const section of ["dependencies", "devDependencies"] as const) {
- for (const key of Object.keys(pkg[section] ?? {})) {
- if (pkg[section]![key] === "workspace:*") {
- pkg[section]![key] = "latest";
- }
- }
- }
- fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-
- const installCmd =
- runner === "pnpm dlx"
- ? "pnpm install"
- : runner === "yarn dlx"
- ? "yarn"
- : runner === "bunx"
- ? "bun install"
- : "npm install";
-
- console.info(`Installing dependencies with: ${installCmd}\n`);
-
- try {
- execSync(installCmd, { stdio: "inherit", cwd: targetDir });
- } catch {
- console.error("\nFailed to install dependencies.");
- process.exit(1);
- }
-
- const installSkill = await shouldInstallSkill(options.skill, !options.noInteractive);
- if (installSkill) {
- runSkillInstall(targetDir);
- }
-
- const devCmd =
- runner === "pnpm dlx"
- ? "pnpm"
- : runner === "yarn dlx"
- ? "yarn"
- : runner === "bunx"
- ? "bun"
- : "npm";
-
- let apiKeyWritten = false;
- if (!options.noInteractive) {
- const { input } = await import("@inquirer/prompts");
- const apiKey = (
- await input({ message: "Enter your OpenAI API key (leave blank to skip):" })
- ).trim();
-
- if (apiKey) {
- fs.writeFileSync(path.join(targetDir, ".env"), `OPENAI_API_KEY=${apiKey}\n`);
- apiKeyWritten = true;
- }
- }
-
- console.info(getStartedMessage(name, devCmd, installSkill, apiKeyWritten));
-}
-
-const getStartedMessage = (
- name: string,
- devCmd: string,
- skillInstalled: boolean,
- apiKeyWritten: boolean,
-) => {
- const envInstructions = apiKeyWritten
- ? "✅ .env file created with your API key."
- : `touch .env
-
-Add your API key to .env:
-OPENAI_API_KEY=sk-your-key-here`;
-
- const skillMessage = skillInstalled
- ? "The OpenUI agent skill was installed.\nAI coding assistants will use it to help you build with OpenUI."
- : "";
-
- return `${skillMessage}
-
-Done!
-Get started:
-
-${envInstructions}
-
-> cd ${name}
-> ${devCmd} run dev
-`;
-};
diff --git a/packages/openui-cli/src/commands/generate.ts b/packages/openui-cli/src/commands/generate.ts
index f6dab897b..2f6c86a29 100644
--- a/packages/openui-cli/src/commands/generate.ts
+++ b/packages/openui-cli/src/commands/generate.ts
@@ -2,6 +2,8 @@ import { execFileSync } from "child_process";
import * as fs from "fs";
import * as path from "path";
+import { CreateError, telemetry } from "../lib/telemetry";
+
export interface GenerateOptions {
out?: string;
jsonSchema?: boolean;
@@ -10,11 +12,15 @@ export interface GenerateOptions {
}
export async function runGenerate(entry: string, options: GenerateOptions): Promise {
+ const t0 = Date.now();
+ telemetry.capture("cli_generate_started", {
+ json_schema: !!options.jsonSchema,
+ out_to_file: !!options.out,
+ });
const entryPath = path.resolve(process.cwd(), entry);
if (!fs.existsSync(entryPath)) {
- console.error(`Error: File not found: ${entryPath}`);
- process.exit(1);
+ throw new CreateError("generate_entry_missing", `File not found: ${entryPath}`);
}
const workerPath = path.join(__dirname, "generate-worker.js");
@@ -32,8 +38,7 @@ export async function runGenerate(entry: string, options: GenerateOptions): Prom
stdio: ["inherit", "pipe", "inherit"],
});
} catch (err) {
- console.error(err);
- process.exit(1);
+ throw new CreateError("generate_worker", err instanceof Error ? err.message : String(err));
}
if (options.out) {
@@ -44,4 +49,10 @@ export async function runGenerate(entry: string, options: GenerateOptions): Prom
} else {
process.stdout.write(output + "\n");
}
+
+ telemetry.capture("cli_generate_succeeded", {
+ json_schema: !!options.jsonSchema,
+ out_to_file: !!options.out,
+ duration_ms: Date.now() - t0,
+ });
}
diff --git a/packages/openui-cli/src/index.ts b/packages/openui-cli/src/index.ts
index 43a2140c5..68486d165 100644
--- a/packages/openui-cli/src/index.ts
+++ b/packages/openui-cli/src/index.ts
@@ -1,29 +1,71 @@
#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+
import { Command } from "commander";
-import { runCreateChatApp } from "./commands/create-chat-app";
+import { runCreateApp } from "./commands/create-app";
import { runGenerate } from "./commands/generate";
import { resolveArgs } from "./lib/resolve-args";
+import { telemetry } from "./lib/telemetry";
+import { handleCliError, normalizeAuth, normalizeTemplate } from "./lib/utils"; // Ensure utils.ts is included for type declarations
const program = new Command();
-program.name("openui").description("CLI for OpenUI").version("0.0.6");
+const cliVersion = (
+ JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")) as {
+ version: string;
+ }
+).version;
+
+program.name("openui").description("CLI for OpenUI").version(cliVersion);
+program.option("--no-telemetry", "Disable anonymous usage analytics");
+
+// Init telemetry once, just before any command runs (honors --no-telemetry / DO_NOT_TRACK).
+program.hook("preAction", (_thisCommand, actionCommand) => {
+ telemetry.init({ cliVersion, flagEnabled: program.opts()["telemetry"] !== false });
+ telemetry.capture("cli_invoked", { command: actionCommand.name() });
+});
program
.command("create")
- .description("Scaffold a new Next.js app with OpenUI Chat")
+ .description("Scaffold a new Next.js app (OpenUI Chat or OpenUI Cloud)")
.option("-n, --name ", "Project name")
+ .option("-t, --template ", "Template: openui-chat | openui-cloud")
+ .option("--api-key ", "OpenUI Cloud API key (cloud template; skips sign-in)")
+ .option("--auth ", "Cloud auth method: oauth | manual | skip")
.option("--skill", "Install the OpenUI agent skill for AI coding assistants")
.option("--no-skill", "Skip installing the OpenUI agent skill")
.option("--no-interactive", "Fail with error if required args are missing")
- .action(async (options: { name?: string; skill?: boolean; interactive: boolean }) => {
- await runCreateChatApp({
- name: options.name,
- skill: options.skill,
- noInteractive: !options.interactive,
- });
- });
+ .option("--no-install", "Scaffold without running the package install")
+ .action(
+ async (options: {
+ name?: string;
+ template?: string;
+ apiKey?: string;
+ auth?: string;
+ skill?: boolean;
+ interactive: boolean;
+ install: boolean;
+ }) => {
+ try {
+ await runCreateApp({
+ name: options.name,
+ template: normalizeTemplate(options.template),
+ apiKey: options.apiKey,
+ auth: normalizeAuth(options.auth),
+ skill: options.skill,
+ noInteractive: !options.interactive,
+ noInstall: !options.install,
+ });
+ } catch (e) {
+ handleCliError(e, "cli_create_failed");
+ } finally {
+ await telemetry.shutdown();
+ }
+ },
+ );
program
.command("generate")
@@ -51,19 +93,25 @@ program
interactive: boolean;
},
) => {
- const args = await resolveArgs(
- {
- entry: entry
- ? { value: entry }
- : {
- prompt: { type: "input", message: "Entry file path?" },
- required: true,
- },
- },
- options.interactive,
- );
+ try {
+ const args = await resolveArgs(
+ {
+ entry: entry
+ ? { value: entry }
+ : {
+ prompt: { type: "input", message: "Entry file path?" },
+ required: true,
+ },
+ },
+ options.interactive,
+ );
- await runGenerate((args as { entry: string }).entry, options);
+ await runGenerate((args as { entry: string }).entry, options);
+ } catch (e) {
+ handleCliError(e, "cli_generate_failed");
+ } finally {
+ await telemetry.shutdown();
+ }
},
);
diff --git a/packages/openui-cli/src/lib/telemetry.ts b/packages/openui-cli/src/lib/telemetry.ts
new file mode 100644
index 000000000..df76a5ce8
--- /dev/null
+++ b/packages/openui-cli/src/lib/telemetry.ts
@@ -0,0 +1,145 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { PostHog } from "posthog-node";
+
+// Public ingestion key (same project as docs/coda-prod). Overridable for testing.
+const POSTHOG_KEY =
+ process.env["OPENUI_POSTHOG_KEY"] ?? "phc_3OLW53x09ZTVZSV6BEpj5uycj3ooqR6KOemOjx04e3D";
+const POSTHOG_HOST = process.env["OPENUI_POSTHOG_HOST"] ?? "https://us.i.posthog.com";
+const SHUTDOWN_TIMEOUT_MS = 2000;
+
+const isTruthyEnv = (v?: string) => v === "1" || v?.toLowerCase() === "true";
+const configDir = () =>
+ path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "openui");
+const isCi = () => {
+ const e = process.env;
+ return isTruthyEnv(e["CI"]) || !!e["GITHUB_ACTIONS"] || !!e["GITLAB_CI"] || !!e["BUILDKITE"];
+};
+
+type Stored = { distinctId: string; firstRunNoticeShown?: boolean };
+
+function loadOrCreateState() {
+ const file = path.join(configDir(), "telemetry.json");
+ try {
+ const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Stored;
+ return {
+ distinctId: raw.distinctId,
+ isFirstRun: !raw.firstRunNoticeShown,
+ persist: () => writeState(file, { ...raw, firstRunNoticeShown: true }),
+ };
+ } catch {
+ /* missing/corrupt → create */
+ }
+ const fresh: Stored = { distinctId: crypto.randomUUID(), firstRunNoticeShown: false };
+ return {
+ distinctId: fresh.distinctId,
+ isFirstRun: true,
+ persist: () => writeState(file, { ...fresh, firstRunNoticeShown: true }),
+ };
+}
+function writeState(file: string, s: Stored) {
+ try {
+ fs.mkdirSync(path.dirname(file), { recursive: true });
+ fs.writeFileSync(file, JSON.stringify(s));
+ } catch {
+ /* read-only fs / CI: best-effort */
+ }
+}
+
+/** Thrown by command funnels so the index wrapper can attribute the failure stage + drain once. */
+export class CreateError extends Error {
+ constructor(
+ public stage: string,
+ message: string,
+ ) {
+ super(message);
+ this.name = "CreateError";
+ }
+}
+
+export class Telemetry {
+ private client?: PostHog;
+ private distinctId = "anonymous";
+ private superProps: Record = {};
+ private enabled = false;
+
+ init(opts: { cliVersion: string; flagEnabled: boolean }) {
+ const optedOut =
+ isTruthyEnv(process.env["DO_NOT_TRACK"]) ||
+ isTruthyEnv(process.env["OPENUI_TELEMETRY_DISABLED"]) ||
+ opts.flagEnabled === false;
+ if (optedOut) return; // enabled stays false → all capture() are no-ops
+ const state = loadOrCreateState();
+ this.distinctId = state.distinctId;
+ this.superProps = {
+ cli_version: opts.cliVersion,
+ os: process.platform,
+ os_release: os.release(),
+ arch: process.arch,
+ node_version: process.version,
+ ci: isCi(),
+ };
+ try {
+ this.client = new PostHog(POSTHOG_KEY, {
+ host: POSTHOG_HOST,
+ flushAt: 1,
+ flushInterval: 0,
+ });
+ // Telemetry is best-effort: swallow network/flush errors so an offline CLI
+ // run never spams the user's console with PostHog stack traces.
+ this.client.on("error", () => {});
+ } catch {
+ return;
+ }
+ this.enabled = true;
+ // posthog-core logs flush failures via a hardcoded console.error (not gated on
+ // any logger/option). Filter ONLY those lines so an offline run stays quiet —
+ // the CLI's own console.error output passes through untouched.
+ const origError = console.error.bind(console);
+ console.error = (...args: unknown[]) => {
+ if (typeof args[0] === "string" && args[0].includes("flushing PostHog")) return;
+ origError(...args);
+ };
+ if (process.env["OPENUI_TELEMETRY_DEBUG"] === "1") this.client.debug();
+ if (state.isFirstRun) {
+ process.stderr.write(
+ "\n◆ OpenUI CLI collects anonymous usage analytics to improve the tool.\n" +
+ " No code, prompts, keys, or personal data are collected.\n" +
+ " Opt out anytime: set DO_NOT_TRACK=1 or pass --no-telemetry.\n\n",
+ );
+ state.persist();
+ }
+ }
+
+ register(props: Record) {
+ if (this.enabled) Object.assign(this.superProps, props);
+ }
+
+ capture(event: string, properties: Record = {}) {
+ if (!this.enabled || !this.client) return;
+ try {
+ this.client.capture({
+ distinctId: this.distinctId,
+ event,
+ properties: { ...this.superProps, ...properties },
+ });
+ } catch {
+ /* telemetry must never throw */
+ }
+ }
+
+ async shutdown() {
+ if (!this.enabled || !this.client) return;
+ try {
+ await Promise.race([
+ this.client.shutdown(),
+ new Promise((r) => setTimeout(r, SHUTDOWN_TIMEOUT_MS)),
+ ]);
+ } catch {
+ /* swallow */
+ }
+ }
+}
+
+export const telemetry = new Telemetry();
diff --git a/packages/openui-cli/src/lib/utils.ts b/packages/openui-cli/src/lib/utils.ts
new file mode 100644
index 000000000..c59467c76
--- /dev/null
+++ b/packages/openui-cli/src/lib/utils.ts
@@ -0,0 +1,30 @@
+import { CloudAuthMethod } from "../auth/mint";
+import { TemplateName } from "../commands/create-app";
+import { CreateError, Telemetry } from "./telemetry";
+
+export function handleCliError(e: unknown, event: string, telemetry?: Telemetry): void {
+ const known = e instanceof CreateError;
+ const message = e instanceof Error ? e.message : String(e);
+ console.error(known ? `Error: ${message}` : message);
+
+ if (telemetry) {
+ telemetry.capture(event, { stage: known ? e.stage : "unknown", error: message.slice(0, 200) });
+ }
+
+ process.exitCode = 1;
+}
+
+export function normalizeTemplate(t?: string): TemplateName | undefined {
+ if (!t) return undefined;
+ const v = t.toLowerCase();
+ if (v === "chat" || v === "openui-chat") return "openui-chat";
+ if (v === "cloud" || v === "openui-cloud") return "openui-cloud";
+ throw new CreateError("bad_args", `unknown template "${t}". Use: openui-chat | openui-cloud.`);
+}
+
+export function normalizeAuth(a?: string): CloudAuthMethod | undefined {
+ if (!a) return undefined;
+ const v = a.toLowerCase();
+ if (v === "oauth" || v === "manual" || v === "skip") return v;
+ throw new CreateError("bad_args", `unknown --auth "${a}". Use: oauth | manual | skip.`);
+}
diff --git a/packages/openui-cli/src/templates/openui-chat/src/app/page.tsx b/packages/openui-cli/src/templates/openui-chat/src/app/page.tsx
index a776fa978..612caddb6 100644
--- a/packages/openui-cli/src/templates/openui-chat/src/app/page.tsx
+++ b/packages/openui-cli/src/templates/openui-chat/src/app/page.tsx
@@ -2,31 +2,34 @@
import "@openuidev/react-ui/components.css";
import "@openuidev/react-ui/styles/index.css";
-import { openAIMessageFormat, openAIReadableStreamAdapter } from "@openuidev/react-headless";
-import { FullScreen } from "@openuidev/react-ui";
+import {
+ openAIMessageFormat,
+ openAIReadableStreamAdapter,
+ type ChatLLM,
+} from "@openuidev/react-headless";
+import { AgentInterface } from "@openuidev/react-ui";
import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui/genui-lib";
const systemPrompt = openuiLibrary.prompt(openuiPromptOptions);
+const llm: ChatLLM = {
+ send: async ({ messages, signal }) =>
+ fetch("/api/chat", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ systemPrompt,
+ messages: openAIMessageFormat.toApi(messages),
+ }),
+ signal,
+ }),
+ streamProtocol: openAIReadableStreamAdapter(),
+};
+
export default function Home() {
return (
-
{
- return fetch("/api/chat", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- systemPrompt,
- messages: openAIMessageFormat.toApi(messages),
- }),
- signal: abortController.signal,
- });
- }}
- streamProtocol={openAIReadableStreamAdapter()}
- componentLibrary={openuiLibrary}
- agentName="OpenUI Chat"
- />
+