feat: implement app-side telemetry sender

Add the shared telemetry sender, wire the CLI/server emit points,
and cover the config and completion behavior with tests.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

cli/src/__tests__/allowed-hostname.test.ts

@@ -44,6 +44,9 @@ function writeBaseConfig(configPath: string) {
       baseUrlMode: "auto",
       disableSignUp: false,
     },
+    telemetry: {
+      enabled: true,
+    },
     storage: {
       provider: "local_disk",
       localDisk: { baseDir: "/tmp/paperclip-storage" },

cli/src/__tests__/doctor.test.ts

@@ -46,6 +46,9 @@ function createTempConfig(): string {
       baseUrlMode: "auto",
       disableSignUp: false,
     },
+    telemetry: {
+      enabled: true,
+    },
     storage: {
       provider: "local_disk",
       localDisk: {

cli/src/__tests__/onboard.test.ts

@@ -44,6 +44,9 @@ function createExistingConfigFixture() {
       baseUrlMode: "auto",
       disableSignUp: false,
     },
+    telemetry: {
+      enabled: true,
+    },
     storage: {
       provider: "local_disk",
       localDisk: {

cli/src/__tests__/telemetry.test.ts

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function makeConfigPath(root: string, enabled: boolean): string {
+  const configPath = path.join(root, ".paperclip", "config.json");
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify({
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-31T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.join(root, "runtime", "db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(root, "runtime", "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(root, "runtime", "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(root, "runtime", "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(root, "runtime", "secrets", "master.key"),
+      },
+    },
+  }, null, 2));
+  return configPath;
+}
+
+describe("cli telemetry", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true })));
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it("respects telemetry.enabled=false from the config file", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-telemetry-"));
+    const configPath = makeConfigPath(root, false);
+    process.env.PAPERCLIP_HOME = path.join(root, "home");
+    process.env.PAPERCLIP_INSTANCE_ID = "telemetry-test";
+
+    const { initTelemetryFromConfigFile } = await import("../telemetry.js");
+    const client = initTelemetryFromConfigFile(configPath);
+
+    expect(client).toBeNull();
+    expect(fs.existsSync(path.join(root, "home", "instances", "telemetry-test", "telemetry", "state.json"))).toBe(false);
+  });
+
+  it("creates telemetry state only after the first event is tracked", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-telemetry-"));
+    process.env.PAPERCLIP_HOME = path.join(root, "home");
+    process.env.PAPERCLIP_INSTANCE_ID = "telemetry-test";
+
+    const { initTelemetry, flushTelemetry } = await import("../telemetry.js");
+    const client = initTelemetry({ enabled: true });
+    const statePath = path.join(root, "home", "instances", "telemetry-test", "telemetry", "state.json");
+
+    expect(client).not.toBeNull();
+    expect(fs.existsSync(statePath)).toBe(false);
+
+    client!.track("install.started", { setupMode: "quickstart" });
+
+    expect(fs.existsSync(statePath)).toBe(true);
+
+    await flushTelemetry();
+  });
+});

cli/src/__tests__/worktree.test.ts

@@ -75,6 +75,9 @@ function buildSourceConfig(): PaperclipConfig {
       publicBaseUrl: "http://127.0.0.1:3100",
       disableSignUp: false,
     },
+    telemetry: {
+      enabled: true,
+    },
     storage: {
       provider: "local_disk",
       localDisk: {

cli/src/commands/client/company.ts

@@ -12,6 +12,8 @@ import type {
   CompanyPortabilityPreviewResult,
   CompanyPortabilityImportResult,
 } from "@paperclipai/shared";
+import { trackCompanyImported } from "@paperclipai/shared/telemetry";
+import { getTelemetryClient } from "../../telemetry.js";
 import { ApiRequestError } from "../../client/http.js";
 import { openUrl } from "../../client/board-auth.js";
 import { binaryContentTypeByExtension, readZipArchive } from "./zip.js";
@@ -1440,6 +1442,12 @@ export function registerCompanyCommands(program: Command): void {
           if (!imported) {
             throw new Error("Import request returned no data.");
           }
+          const tc = getTelemetryClient();
+          if (tc) {
+            const isPrivate = sourcePayload.type !== "github";
+            const sourceRef = sourcePayload.type === "github" ? sourcePayload.url : from;
+            trackCompanyImported(tc, { sourceType: sourcePayload.type, sourceRef, isPrivate });
+          }
           let companyUrl: string | undefined;
           if (!ctx.json) {
             try {

cli/src/commands/configure.ts

@@ -63,6 +63,9 @@ function defaultConfig(): PaperclipConfig {
       baseUrlMode: "auto",
       disableSignUp: false,
     },
+    telemetry: {
+      enabled: true,
+    },
     storage: defaultStorageConfig(),
     secrets: defaultSecretsConfig(),
   };

cli/src/commands/onboard.ts

@@ -33,6 +33,8 @@ import {
 } from "../config/home.js";
 import { bootstrapCeoInvite } from "./auth-bootstrap-ceo.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
+import { getTelemetryClient } from "../telemetry.js";
+import { trackInstallStarted, trackInstallCompleted } from "@paperclipai/shared/telemetry";
 
 type SetupMode = "quickstart" | "advanced";
 
@@ -356,6 +358,9 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     setupMode = setupModeChoice as SetupMode;
   }
 
+  const tc = getTelemetryClient();
+  if (tc) trackInstallStarted(tc, { setupMode });
+
   let llm: PaperclipConfig["llm"] | undefined;
   const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv();
   let {
@@ -488,6 +493,9 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     logging,
     server,
     auth,
+    telemetry: {
+      enabled: true,
+    },
     storage,
     secrets,
   };
@@ -501,6 +509,12 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
 
   writeConfig(config, opts.config);
 
+  if (tc) trackInstallCompleted(tc, {
+    setupMode,
+    dbMode: database.mode,
+    deploymentMode: server.deploymentMode,
+  });
+
   p.note(
     [
       `Database: ${database.mode}`,

cli/src/commands/worktree-lib.ts

@@ -224,6 +224,9 @@ export function buildWorktreeConfig(input: {
       ...(authPublicBaseUrl ? { publicBaseUrl: authPublicBaseUrl } : {}),
       disableSignUp: source?.auth.disableSignUp ?? false,
     },
+    telemetry: {
+      enabled: source?.telemetry?.enabled ?? true,
+    },
     storage: {
       provider: source?.storage.provider ?? "local_disk",
       localDisk: {

cli/src/index.ts

@@ -18,9 +18,11 @@ import { registerDashboardCommands } from "./commands/client/dashboard.js";
 import { registerFeedbackCommands } from "./commands/client/feedback.js";
 import { applyDataDirOverride, type DataDirOptionLike } from "./config/data-dir.js";
 import { loadPaperclipEnvFile } from "./config/env.js";
+import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
 import { registerWorktreeCommands } from "./commands/worktree.js";
 import { registerPluginCommands } from "./commands/client/plugin.js";
 import { registerClientAuthCommands } from "./commands/client/auth.js";
+import { cliVersion } from "./version.js";
 
 const program = new Command();
 const DATA_DIR_OPTION_HELP =
@@ -29,7 +31,7 @@ const DATA_DIR_OPTION_HELP =
 program
   .name("paperclipai")
   .description("Paperclip CLI — setup, diagnose, and configure your instance")
-  .version("0.2.7");
+  .version(cliVersion);
 
 program.hook("preAction", (_thisCommand, actionCommand) => {
   const options = actionCommand.optsWithGlobals() as DataDirOptionLike;
@@ -39,6 +41,7 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
     hasContextOption: optionNames.has("context"),
   });
   loadPaperclipEnvFile(options.config);
+  initTelemetryFromConfigFile(options.config);
 });
 
 program
@@ -156,7 +159,20 @@ auth
 
 registerClientAuthCommands(auth);
 
-program.parseAsync().catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
-});
+async function main(): Promise<void> {
+  let failed = false;
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    failed = true;
+    console.error(err instanceof Error ? err.message : String(err));
+  } finally {
+    await flushTelemetry();
+  }
+
+  if (failed) {
+    process.exit(1);
+  }
+}
+
+void main();

cli/src/telemetry.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import {
+  TelemetryClient,
+  resolveTelemetryConfig,
+  loadOrCreateState,
+} from "@paperclipai/shared/telemetry";
+import { resolvePaperclipInstanceRoot } from "./config/home.js";
+import { readConfig } from "./config/store.js";
+import { cliVersion } from "./version.js";
+
+let client: TelemetryClient | null = null;
+
+export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClient | null {
+  if (client) return client;
+
+  const config = resolveTelemetryConfig(fileConfig);
+  if (!config.enabled) return null;
+
+  const stateDir = path.join(resolvePaperclipInstanceRoot(), "telemetry");
+  client = new TelemetryClient(config, () => loadOrCreateState(stateDir, cliVersion), cliVersion);
+  return client;
+}
+
+export function initTelemetryFromConfigFile(configPath?: string): TelemetryClient | null {
+  try {
+    return initTelemetry(readConfig(configPath)?.telemetry);
+  } catch {
+    return initTelemetry();
+  }
+}
+
+export function getTelemetryClient(): TelemetryClient | null {
+  return client;
+}
+
+export async function flushTelemetry(): Promise<void> {
+  if (client) {
+    await client.flush();
+  }
+}

cli/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module";
+
+type PackageJson = {
+  version?: string;
+};
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json") as PackageJson;
+
+export const cliVersion = pkg.version ?? "0.0.0";