The Open Standard for Generative UI
Add CLI agent instrumentation (#779)
Zahle Khan7901d584820b
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdxindex 1d2b94d06..d5ba4c163 100644--- a/docs/content/docs/api-reference/cli.mdx+++ b/docs/content/docs/api-reference/cli.mdx@@ -53,16 +53,17 @@ openui create [options]**Options**-| Flag | Description |-| --------------------------- | --------------------------------------------------------- |-| `-n, --name <string>` | Project name (directory to create) |-| `-t, --template <template>` | AI setup/template: `openui-cloud` or `openui-self-hosted` |-| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |-| `--auth <method>` | Cloud auth method: `oauth`, `manual`, or `skip` |-| `--skill` | Install the OpenUI agent skill for AI coding assistants |-| `--no-skill` | Skip installing the OpenUI agent skill |-| `--no-install` | Scaffold without running dependency installation |-| `--no-interactive` | Fail instead of prompting for missing input |+| Flag | Description |+| --------------------------- | ----------------------------------------------------------- |+| `-n, --name <string>` | Project name (directory to create) |+| `-t, --template <template>` | AI setup/template: `openui-cloud` or `openui-self-hosted` |+| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |+| `--auth <method>` | Cloud auth method: `oauth`, `manual`, or `skip` |+| `--skill` | Install the OpenUI agent skill for AI coding assistants |+| `--no-skill` | Skip installing the OpenUI agent skill |+| `--no-install` | Scaffold without running dependency installation |+| `--no-interactive` | Fail instead of prompting for missing input |+| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |When run interactively (default), the CLI prompts for any missing options. It asks you to choose your AI setup: **OpenUI Cloud** is the fastest setup with free hosted models, while **OpenAI-compatible provider** uses your own key and self-hosts the AI route in the generated app. Pass `--no-interactive` in CI or scripted environments to surface missing required flags as errors instead.@@ -173,6 +174,7 @@ openui generate [entry] [options]| `--export <name>` | Name of the export to use (auto-detected by default) || `--prompt-options <name>` | Name of the `PromptOptions` export to use (auto-detected by default) || `--no-interactive` | Fail instead of prompting for missing `entry` |+| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |**Examples**@@ -318,11 +320,12 @@ The spec is a handover artifact: the team that owns the component library genera**Options**-| Flag | Description |-| ------------------ | ---------------------------------------------------- |-| `-o, --out <file>` | Write output to a file instead of stdout |-| `--export <name>` | Name of the export to use (auto-detected by default) |-| `--no-interactive` | Fail instead of prompting for missing `entry` |+| Flag | Description |+| --------------------- | ----------------------------------------------------------- |+| `-o, --out <file>` | Write output to a file instead of stdout |+| `--export <name>` | Name of the export to use (auto-detected by default) |+| `--no-interactive` | Fail instead of prompting for missing `entry` |+| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |Entry bundling and library detection work the same as [`openui generate`](#export-auto-detection). `PromptOptions` exports are not folded into the spec — the spec is pure library data; consumers apply prompt customisation separately when they build the system prompt.@@ -397,6 +400,20 @@ npx @openuidev/cli@latest generate-spec ./src/library.ts --out ./library-spec.jsnpx @openuidev/cli@latest generate-spec ./src/library.ts --export myLibrary```+## Coding-agent attribution++When a coding agent invokes any CLI command, it should pass `--agent-name` using its stable,+lowercase kebab-case product slug. Examples include `codex`, `claude-code`, `cline`,+`factory-droid`, and `pi`. Do not pass a model/version, user name, session ID, or another unique+value. Humans can omit the option; its default is `unknown`.++Usage analytics include two independent properties: `agent_name`, declared through the option,+and `detected_agent_name`, inferred best-effort from known product environment markers. Either+value can be spoofed, inherited, missing, or ambiguous, so neither should be treated as an+authentication or security signal. For `create`, analytics also include `package_manager`, the+manager selected for dependency installation (`npm`, `pnpm`, `yarn`, or `bun`). Use+`--no-telemetry` or `DO_NOT_TRACK=1` to disable collection.+## See also<Cards>diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.mdindex 1f22abe13..3fa1afed6 100644--- a/packages/openui-cli/README.md+++ b/packages/openui-cli/README.md@@ -71,6 +71,7 @@ Options:- `--no-interactive`: Fail instead of prompting for missing required input- `--api-key <key>`: (cloud template) OpenUI Cloud API key; skips sign-in- `--auth <method>`: (cloud template) How to obtain the key — `oauth`, `manual`, or `skip`+- `--agent-name <name>`: Declare the invoking coding agent as a lowercase kebab-case product slug (default: `unknown`)What it does:@@ -123,6 +124,7 @@ Options:- `--export <name>`: Use a specific export name instead of auto-detecting the library export- `--prompt-options <name>`: Use a specific `PromptOptions` export name (auto-detected by default)- `--no-interactive`: Fail instead of prompting for a missing `entry`+- `--agent-name <name>`: Declare the invoking coding agent as a lowercase kebab-case product slug (default: `unknown`)What it does:@@ -182,7 +184,11 @@ node dist/index.js generate --help## Telemetry-The CLI sends usage analytics; OAuth sign-ins may link usage to your OIDC account ID. It does not send code, prompts, API keys, email, or name. Disable telemetry with `--no-telemetry` or `DO_NOT_TRACK=1`.+The CLI sends usage analytics; OAuth sign-ins may link usage to your OIDC account ID. It does not send code, prompts, API keys, email, or personal names.++When a coding agent invokes the CLI, it should pass `--agent-name` using its stable, lowercase kebab-case product slug—for example, `codex`, `claude-code`, `cline`, `factory-droid`, or `pi`. Do not pass a model/version, user name, session ID, or other unique value. Humans can omit the flag; it defaults to `unknown`.++Telemetry includes both `agent_name` (the CLI declaration) and `detected_agent_name` (best-effort environment detection). Either can be spoofed, inherited, missing, or ambiguous; neither is an authentication signal. For `create`, telemetry also includes `package_manager`, the manager selected for dependency installation (`npm`, `pnpm`, `yarn`, or `bun`). Disable telemetry with `--no-telemetry` or `DO_NOT_TRACK=1`.```bashopenui create --no-telemetrydiff --git a/packages/openui-cli/src/commands/create-app.ts b/packages/openui-cli/src/commands/create-app.tsindex c9c5a09df..cf21ade50 100644--- a/packages/openui-cli/src/commands/create-app.ts+++ b/packages/openui-cli/src/commands/create-app.ts@@ -57,8 +57,9 @@ function rewritePackageJson(projectDir: string, name: string) {export async function runCreateApp(options: CreateAppOptions): Promise<void> {const interactive = !options.noInteractive;+ const packageManager = resolveInstallPackageManager();const t0 = Date.now();- telemetry.register({ interactive });+ telemetry.register({ interactive, package_manager: packageManager.name });telemetry.capture("cli_create_started", {...createFunnelProps("create_started"),interactive,@@ -111,7 +112,6 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {throw new CreateError("dir_exists", `Directory "${name}" already exists.`);}- const packageManager = resolveInstallPackageManager();const templateDir = path.join(__dirname, "..", "templates", template);if (!fs.existsSync(templateDir)) {throw new CreateError(diff --git a/packages/openui-cli/src/index.ts b/packages/openui-cli/src/index.tsindex 1dcead05a..813696898 100644--- a/packages/openui-cli/src/index.ts+++ b/packages/openui-cli/src/index.ts@@ -7,6 +7,7 @@ import { Command } from "commander";import { runCreateApp } from "./commands/create-app";import { runGenerate } from "./commands/generate";+import { detectAgent, UNKNOWN_AGENT_NAME } from "./lib/detect-agent";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@@ -22,9 +23,21 @@ const cliVersion = (program.name("openui").description("CLI for OpenUI").version(cliVersion);program.option("--no-telemetry", "Disable anonymous usage analytics");+program.option(+ "--agent-name <name>",+ "AI agents: declare your stable lowercase kebab-case product slug for telemetry (e.g. codex or claude-code); humans can omit",+ UNKNOWN_AGENT_NAME,+);+program.configureHelp({ showGlobalOptions: true });+// 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 });+ const globalOptions = program.opts<{ agentName: string; telemetry?: boolean }>();+ telemetry.init({ cliVersion, flagEnabled: globalOptions.telemetry !== false });+ telemetry.register({+ agent_name: globalOptions.agentName,+ detected_agent_name: detectAgent(),+ });telemetry.capture("cli_invoked", { command: actionCommand.name() });});diff --git a/packages/openui-cli/src/lib/detect-agent.ts b/packages/openui-cli/src/lib/detect-agent.tsnew file mode 100644index 000000000..9314af51c--- /dev/null+++ b/packages/openui-cli/src/lib/detect-agent.ts@@ -0,0 +1,33 @@+export const UNKNOWN_AGENT_NAME = "unknown";++export type DetectedAgentName =+ | "claude-code"+ | "cline"+ | "codex"+ | "factory-droid"+ | "pi"+ | "ambiguous"+ | typeof UNKNOWN_AGENT_NAME;++const isTruthyEnv = (value?: string) => value === "1" || value?.toLowerCase() === "true";+const isPresent = (value?: string) => Boolean(value?.trim());++/**+ * Best-effort detection from environment markers set by coding-agent products.+ * These markers are not an authentication boundary: callers can spoof or inherit them.+ */+export function detectAgent(env: NodeJS.ProcessEnv = process.env): DetectedAgentName {+ const matches = new Set<Exclude<DetectedAgentName, "ambiguous" | "unknown">>();++ if (env["CLAUDE_CODE_CHILD_SESSION"] === "1" || env["CLAUDECODE"] === "1") {+ matches.add("claude-code");+ }+ if (isPresent(env["CODEX_THREAD_ID"])) matches.add("codex");+ if (isTruthyEnv(env["CLINE_ACTIVE"])) matches.add("cline");+ if (isPresent(env["FACTORY_PROJECT_DIR"])) matches.add("factory-droid");+ if (isTruthyEnv(env["PI_CODING_AGENT"])) matches.add("pi");++ if (matches.size === 0) return UNKNOWN_AGENT_NAME;+ if (matches.size > 1) return "ambiguous";+ return [...matches][0] ?? UNKNOWN_AGENT_NAME;+}diff --git a/packages/openui-cli/src/lib/telemetry.ts b/packages/openui-cli/src/lib/telemetry.tsindex bbdb9e79a..88e2e624e 100644--- a/packages/openui-cli/src/lib/telemetry.ts+++ b/packages/openui-cli/src/lib/telemetry.ts@@ -117,7 +117,7 @@ export class Telemetry {if (state.isFirstRun) {process.stderr.write("\n◆ OpenUI CLI collects usage analytics; OAuth sign-ins may link usage to your OIDC account ID.\n" +- " No code, prompts, API keys, email, or name are collected. Opt out: set DO_NOT_TRACK=1 or pass --no-telemetry.\n\n",+ " No code, prompts, API keys, email, or personal name are collected. Opt out: set DO_NOT_TRACK=1 or pass --no-telemetry.\n\n",);state.persist();}