feat(cli): track agent usage and deprioritize Neon

Author: tannerlinsley

.changeset/friendly-eels-divide.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/cli': minor
+'@tanstack/create': patch
+---
+
+Add anonymous CLI telemetry with command and step tracking, a hidden `--agent` flag for agent-originated invocations, first-run disclosure, and opt-out controls via config, env vars, and `tanstack telemetry` commands.
+
+Deprioritize the Neon add-on in create flows without removing support for the add-on itself.

packages/cli/src/cli.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 import { resolve } from 'node:path'
-import { Command, InvalidArgumentError } from 'commander'
+import { Command, InvalidArgumentError, Option } from 'commander'
 import { cancel, confirm, intro, isCancel, log } from '@clack/prompts'
 import chalk from 'chalk'
 import semver from 'semver'
@@ -85,6 +85,26 @@ function sanitizeIdList(values: Array<string>) {
   )
 }
 
+const AGENT_FLAG = '--agent'
+
+function addHiddenAgentFlag<T extends Command>(cmd: T) {
+  if (cmd.options.some((option) => option.long === AGENT_FLAG)) {
+    return cmd
+  }
+
+  cmd.addOption(
+    new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+  )
+
+  return cmd
+}
+
+function getInvocationTelemetryProperties() {
+  return {
+    invoked_by_agent: process.argv.includes(AGENT_FLAG),
+  }
+}
+
 function getStarterTelemetryProperties(value?: string) {
   if (!value) {
     return {}
@@ -417,6 +437,7 @@ export function cli({
     const startedAt = Date.now()
     currentTelemetry = telemetry
     telemetry.captureCommandStarted(command, {
+      ...getInvocationTelemetryProperties(),
       ...opts.properties,
       cli_version: VERSION,
     })
@@ -438,6 +459,8 @@ export function cli({
     .description(`${appName} CLI`)
     .version(VERSION, '-v, --version', 'output the current version')
 
+  addHiddenAgentFlag(program)
+
   // Helper to create the create command action handler
   async function handleCreate(projectName: string, options: CliOptions) {
     try {
@@ -710,6 +733,7 @@ export function cli({
 
   // Helper to configure create command options
   function configureCreateCommand(cmd: Command) {
+    addHiddenAgentFlag(cmd)
     cmd.argument('[project-name]', 'name of the project')
 
     if (!defaultFramework) {
@@ -917,6 +941,9 @@ export function cli({
   program
     .command('libraries')
     .description('List TanStack libraries')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .option(
       '--group <group>',
       `filter by group (${LIBRARY_GROUPS.join(', ')})`,
@@ -991,6 +1018,9 @@ export function cli({
   program
     .command('doc')
     .description('Fetch a TanStack documentation page')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .argument('<library>', 'library ID (eg. query, router, table)')
     .argument('<path>', 'documentation path (eg. framework/react/overview)')
     .option('--docs-version <version>', 'docs version (default: latest)', 'latest')
@@ -1098,6 +1128,9 @@ export function cli({
   program
     .command('search-docs')
     .description('Search TanStack documentation')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .argument('<query>', 'search query')
     .option('--library <id>', 'filter to specific library')
     .option('--framework <name>', 'filter to specific framework')
@@ -1164,6 +1197,9 @@ export function cli({
   program
     .command('ecosystem')
     .description('List TanStack ecosystem partners')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .option('--category <category>', 'filter by category')
     .option('--library <id>', 'filter by TanStack library')
     .option('--json', 'output JSON for automation', false)
@@ -1251,6 +1287,9 @@ export function cli({
   program
     .command('pin-versions')
     .description('Pin versions of the TanStack libraries')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('pin-versions', {}, async (telemetry) => {
@@ -1333,6 +1372,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   telemetryCommand
     .command('status')
     .description('Show anonymous telemetry status')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .option('--json', 'output JSON for automation', false)
     .action(async (options: { json: boolean }) => {
       const status = await getTelemetryStatus({ createIfMissing: true })
@@ -1359,6 +1401,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   telemetryCommand
     .command('enable')
     .description('Enable anonymous telemetry')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       await setTelemetryEnabled(true)
       console.log('Anonymous telemetry enabled')
@@ -1367,6 +1412,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   telemetryCommand
     .command('disable')
     .description('Disable anonymous telemetry')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       await setTelemetryEnabled(false)
       console.log('Anonymous telemetry disabled')
@@ -1375,6 +1423,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   // === ADD SUBCOMMAND ===
   program
     .command('add')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .argument(
       '[add-on...]',
       'Name of the add-ons (or add-ons separated by spaces or commas)',
@@ -1437,6 +1488,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   addOnCommand
     .command('init')
     .description('Initialize an add-on from the current project')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('add-on:init', {}, async () => {
@@ -1450,6 +1504,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   addOnCommand
     .command('compile')
     .description('Update add-on from the current project')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('add-on:compile', {}, async () => {
@@ -1465,6 +1522,9 @@ Remove your node_modules directory and package lock file and re-install.`,
     .description(
       'Watch project files and continuously refresh .add-on and add-on.json',
     )
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('add-on:dev', {}, async () => {
@@ -1481,6 +1541,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   templateCommand
     .command('init')
     .description('Initialize a project template from the current project')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('template:init', {}, async () => {
@@ -1494,6 +1557,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   templateCommand
     .command('compile')
     .description('Compile the template JSON file for the current project')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('template:compile', {}, async () => {
@@ -1510,6 +1576,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   starterCommand
     .command('init')
     .description('Deprecated alias: initialize a project template')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('starter:init', {}, async () => {
@@ -1523,6 +1592,9 @@ Remove your node_modules directory and package lock file and re-install.`,
   starterCommand
     .command('compile')
     .description('Deprecated alias: compile the template JSON file')
+    .addOption(
+      new Option(AGENT_FLAG, 'internal: invocation originated from an agent').hideHelp(),
+    )
     .action(async () => {
       try {
         await runWithTelemetry('starter:compile', {}, async () => {

packages/cli/src/telemetry.ts

@@ -21,12 +21,14 @@ interface PendingStep {
   type: StatusStepType
 }
 
-const POSTHOG_API_HOST = 'https://us.i.posthog.com'
-const POSTHOG_CAPTURE_ENDPOINT = `${POSTHOG_API_HOST}/capture/`
-const POSTHOG_PROJECT_TOKEN = 'phc_xJ2VBahJBzy3BShLhuGpw7EyoSuQtgwXXvhE9BYtHuKQ'
+const TELEMETRY_TRANSPORT_ENDPOINT = 'https://www.google-analytics.com/g/collect'
+const TELEMETRY_PROPERTY_ID = 'G-JMT1Z50SPS'
 const TELEMETRY_NOTICE =
   'TanStack CLI sends anonymous usage telemetry by default. It never sends project names, paths, raw search text, template URLs, add-on config values, or raw error messages. Disable it with `tanstack telemetry disable` or `TANSTACK_CLI_TELEMETRY_DISABLED=1`.'
 const TELEMETRY_TIMEOUT_MS = 1200
+const TELEMETRY_VALUE_MAX_LENGTH = 500
+const TELEMETRY_NUMERIC_PREFIX = 'epn.'
+const TELEMETRY_STRING_PREFIX = 'ep.'
 
 let telemetryStatusPromise: Promise<Awaited<ReturnType<typeof getTelemetryStatus>>> | undefined
 
@@ -56,6 +58,75 @@ function cleanProperties(value: unknown): unknown {
   return value
 }
 
+function truncateValue(value: string) {
+  return value.length > TELEMETRY_VALUE_MAX_LENGTH
+    ? `${value.slice(0, TELEMETRY_VALUE_MAX_LENGTH - 1)}…`
+    : value
+}
+
+function normalizeParamKey(key: string) {
+  const normalized = key.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^_+/, '')
+  const prefixed = /^[a-zA-Z]/.test(normalized)
+    ? normalized
+    : `p_${normalized || 'value'}`
+
+  return prefixed.slice(0, 40)
+}
+
+function normalizeParamValue(value: unknown): number | string | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 1 : 0
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined
+  }
+
+  if (typeof value === 'string') {
+    return truncateValue(value)
+  }
+
+  const cleaned = cleanProperties(value)
+  if (cleaned === undefined) {
+    return undefined
+  }
+
+  return truncateValue(JSON.stringify(cleaned))
+}
+
+function createTelemetryRequestBody(
+  event: string,
+  distinctId: string,
+  properties: TelemetryProperties,
+) {
+  const params = new URLSearchParams({
+    cid: distinctId,
+    en: event,
+    tid: TELEMETRY_PROPERTY_ID,
+    v: '2',
+  })
+
+  for (const [key, value] of Object.entries(properties)) {
+    const normalizedValue = normalizeParamValue(value)
+    if (normalizedValue === undefined) {
+      continue
+    }
+
+    const normalizedKey = normalizeParamKey(key)
+    const paramName =
+      typeof normalizedValue === 'number'
+        ? `${TELEMETRY_NUMERIC_PREFIX}${normalizedKey}`
+        : `${TELEMETRY_STRING_PREFIX}${normalizedKey}`
+    params.append(paramName, String(normalizedValue))
+  }
+
+  return params.toString()
+}
+
 function getErrorCode(error: unknown) {
   if (!error || typeof error !== 'object') {
     return 'unknown_error'
@@ -106,17 +177,12 @@ async function postEvent(event: string, distinctId: string, properties: Telemetr
   }, TELEMETRY_TIMEOUT_MS)
 
   try {
-    await fetch(POSTHOG_CAPTURE_ENDPOINT, {
+    await fetch(TELEMETRY_TRANSPORT_ENDPOINT, {
       method: 'POST',
       headers: {
-        'Content-Type': 'application/json',
+        'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
       },
-      body: JSON.stringify({
-        api_key: POSTHOG_PROJECT_TOKEN,
-        distinct_id: distinctId,
-        event,
-        properties,
-      }),
+      body: createTelemetryRequestBody(event, distinctId, properties),
       signal: controller.signal,
     })
   } catch {
@@ -235,7 +301,7 @@ export class TelemetryClient {
 
   private baseProperties() {
     return {
-      $lib: 'tanstack-cli',
+      client_lib: 'tanstack-cli',
       disabled_by: this.disabledBy,
       node_major: getNodeMajorVersion(),
       os_arch: process.arch,