Skip to content

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.mdx
index 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.js
npx @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.md
index 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`.
```bash
openui create --no-telemetry
diff --git a/packages/openui-cli/src/commands/create-app.ts b/packages/openui-cli/src/commands/create-app.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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();
}