The Open Standard for Generative UI
import { loadTelemetryState, saveTelemetryState } from "#openui-telemetry-state";
import * as os from "node:os";
import type { PostHog } from "posthog-node";
import { isTruthyEnv } from "./env";
import { cliErrorProperties } from "./errors";
import { createPostHogClient } from "./posthog";
import type { RetryAttemptInfo } from "./retry";
const SHUTDOWN_TIMEOUT_MS = 2000;
const isTelemetryDebug = () => process.env["OPENUI_TELEMETRY_DEBUG"] === "1";
const isCi = () => {
const e = process.env;
return isTruthyEnv(e["CI"]) || !!e["GITHUB_ACTIONS"] || !!e["GITLAB_CI"] || !!e["BUILDKITE"];
};
const debugLogPostHogFailure = (stage: string, error: unknown) => {
if (!isTelemetryDebug()) return;
const message = error instanceof Error ? error.message : String(error);
console.warn(`[OpenUI telemetry] PostHog ${stage} failed: ${message}`);
};
type Session = {
client?: PostHog;
distinctId: string;
superProps: Record<string, unknown>;
enabled: boolean;
};
export class Telemetry {
private readonly session: Session;
constructor(source?: Telemetry) {
this.session = source?.session ?? {
distinctId: "anonymous",
superProps: {},
enabled: false,
};
}
init(opts: {
cliVersion: string;
flagEnabled: boolean;
detectedInteractive: boolean;
detectedAgentName: string;
}) {
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
let telemetryState = loadTelemetryState();
if (telemetryState.changed) {
telemetryState = saveTelemetryState(telemetryState, telemetryState.state);
}
this.session.distinctId = telemetryState.state.distinctId;
this.session.superProps = {
cli_version: opts.cliVersion,
os: process.platform,
os_release: os.release(),
arch: process.arch,
node_version: process.version,
ci: isCi(),
stdin_is_tty: Boolean(process.stdin.isTTY),
stdout_is_tty: Boolean(process.stdout.isTTY),
is_interactive_terminal: opts.detectedInteractive,
detected_agent_name: opts.detectedAgentName,
};
try {
this.session.client = createPostHogClient();
// Telemetry is best-effort: swallow network/flush errors so an offline CLI
// run never spams the user's console with PostHog stack traces.
this.session.client.on("error", (error) => debugLogPostHogFailure("request", error));
} catch (error) {
debugLogPostHogFailure("init", error);
return;
}
this.session.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 (isTelemetryDebug()) this.session.client.debug();
if (telemetryState.state["firstRunNoticeShown"] !== true) {
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 personal name are collected. Opt out: set DO_NOT_TRACK=1 or pass --no-telemetry.\n\n",
);
saveTelemetryState(telemetryState, { ...telemetryState.state, firstRunNoticeShown: true });
}
}
register(props: Record<string, unknown>) {
if (this.session.enabled) Object.assign(this.session.superProps, props);
}
registerRun(props: {
agent_name: string;
can_prompt: boolean;
/** false when `--no-interactive` is passed; only sent for commands that have the flag. */
interactive?: boolean;
cli_run_id: string;
command: string;
}) {
this.register(props);
}
trackInvoked() {
this.capture("cli_invoked");
}
reportNetworkRetry(stage: string): (info: RetryAttemptInfo) => void {
return (info) => {
const properties = cliErrorProperties(info.error);
this.capture("cli_network_retry", {
failure_stage: stage,
attempt: info.attempt,
max_attempts: info.maxAttempts,
delay_ms: info.delayMs,
error_class: properties.error_class,
error_code: properties.error_code,
});
};
}
capture(event: string, properties: Record<string, unknown> = {}) {
const { enabled, client, distinctId, superProps } = this.session;
if (!enabled || !client) return;
try {
client.capture({
distinctId,
event,
properties: { ...superProps, ...properties },
});
} catch (error) {
debugLogPostHogFailure("capture", error);
}
}
alias(distinctId: string, alias: string) {
const { enabled, client } = this.session;
if (!enabled || !client) return;
if (!distinctId || !alias || distinctId === alias) return;
try {
client.alias({ distinctId, alias });
client.setPersonProperties({
distinctId,
propertiesOnce: {
first_cli_auth_ts: new Date().toISOString(),
},
});
} catch (error) {
debugLogPostHogFailure("alias", error);
}
}
aliasOidcSubject(oidcSub: string) {
const { enabled, client, distinctId } = this.session;
if (!enabled || !client || !oidcSub || oidcSub === distinctId) {
return;
}
this.alias(oidcSub, distinctId);
}
async shutdown() {
const { enabled, client } = this.session;
if (!enabled || !client) return;
try {
await Promise.race([
client.shutdown(),
new Promise<void>((r) => setTimeout(r, SHUTDOWN_TIMEOUT_MS)),
]);
} catch (error) {
debugLogPostHogFailure("shutdown", error);
}
}
}
export const telemetry = new Telemetry();