Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

feat(cli): add telemetry transparency — persistent config, notice, and docs (#795)

Jakub Sieradzki8d426b940f33
diff --git a/apps/docs/v2/telemetry.mdx b/apps/docs/v2/telemetry.mdx
new file mode 100644
index 000000000..afdaace34
--- /dev/null
+++ b/apps/docs/v2/telemetry.mdx
@@ -0,0 +1,67 @@
+---
+title: "Telemetry"
+description: "Learn about the anonymous usage data collected by the Mercur CLI"
+---
+
+## Overview
+
+The Mercur CLI collects **anonymous usage data** to help us understand how the CLI is used and improve the developer experience. This data is collected by default but can be easily disabled.
+
+## What We Collect
+
+When you run CLI commands (`create`, `init`, `add`, `registry:build`), the following data is sent:
+
+| Data | Description |
+|------|-------------|
+| Event type | Which command was run and its outcome |
+| Node.js version | Your Node.js runtime version |
+| Node environment | The `NODE_ENV` value |
+| Mercur version | Version of `@mercurjs/core` in your project |
+| Medusa version | Version of `@medusajs/framework` in your project |
+| Package manager | npm, yarn, pnpm, or bun |
+| Project structure | Whether `src/` directory is used, alias prefix |
+| System info | OS, platform, architecture, CPU model/speed/count, RAM |
+| Environment | Whether running in WSL, Docker, or a TTY |
+| Deployment vendor | Detected hosting platform (Railway, Fly.io, Heroku, etc.) |
+| Project ID | SHA-256 hash (base64) of your git remote URL — **not the URL itself** |
+| Project config | Contents of your `blocks.json` configuration |
+| Email | **Only** if you voluntarily provided it during `mercurjs create` |
+
+## What We Do NOT Collect
+
+- Source code or file contents
+- File names or directory structure
+- Git history or commit messages
+- Personal data (beyond the optional email above)
+
+## How to Opt Out
+
+### Using the CLI
+
+```bash
+mercurjs telemetry --disable
+```
+
+### Using an environment variable
+
+```bash
+export MERCUR_DISABLE_TELEMETRY=true
+```
+
+This is useful for CI/CD environments or shared configurations.
+
+### Check current status
+
+```bash
+mercurjs telemetry
+```
+
+## Where Data Goes
+
+Telemetry events are sent to `https://telemetry.mercurjs.com`. The data is used exclusively by the Mercur team to prioritize features and fix issues.
+
+## Re-enabling Telemetry
+
+```bash
+mercurjs telemetry --enable
+```
diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.ts
index ab46f090e..77260345f 100644
--- a/packages/cli/src/commands/add.ts
+++ b/packages/cli/src/commands/add.ts
@@ -11,7 +11,7 @@ import { highlighter } from "../utils/highlighter";
import { logger } from "../utils/logger";
import { runInit } from "./init";
import { handleError } from "../utils/handle-error";
-import { sendTelemetryEvent } from "../telemetry";
+import { sendTelemetryEvent, showTelemetryNoticeIfNeeded } from "../telemetry";
export const addOptionsSchema = z.object({
blocks: z.array(z.string()).optional(),
@@ -35,6 +35,7 @@ export const add = new Command()
.option("-s, --silent", "mute output.", false)
.action(async (items, opts) => {
try {
+ showTelemetryNoticeIfNeeded();
const options = addOptionsSchema.parse({
blocks: items,
cwd: path.resolve(opts.cwd),
diff --git a/packages/cli/src/commands/create.ts b/packages/cli/src/commands/create.ts
index 3547262d3..c3ac92e83 100644
--- a/packages/cli/src/commands/create.ts
+++ b/packages/cli/src/commands/create.ts
@@ -4,7 +4,7 @@ import { pipeline } from "node:stream/promises";
import path from "path";
import { clearRegistryContext } from "@/src/registry/context";
-import { sendTelemetryEvent, setTelemetryEmail } from "@/src/telemetry";
+import { sendTelemetryEvent, setTelemetryEmail, showTelemetryNoticeIfNeeded } from "@/src/telemetry";
import { setupDatabase, type SetupDatabaseResult } from "@/src/utils/create-db";
import { getPackageManager } from "@/src/utils/get-package-manager";
import { handleError } from "@/src/utils/handle-error";
@@ -56,6 +56,7 @@ export const create = new Command()
.action(async (name, opts) => {
try {
validateNodeVersion();
+ showTelemetryNoticeIfNeeded();
let projectName = name;
if (!projectName) {
@@ -383,7 +384,7 @@ ${header("Documentation:")}
}
function feedbackOutro(): string {
- return `${kleur.bgCyan(kleur.black(" Have feedback? "))} Visit us on ${createTerminalLink("GitHub", "https://github.com/mercurjs/mercur")}.`;
+ return `${kleur.bgCyan(kleur.black(" Have feedback? "))} Visit us on ${createTerminalLink("GitHub", "https://github.com/mercurjs/mercur")}.\n${kleur.bgMagenta(kleur.black(" Join the community! "))} Chat with us on ${createTerminalLink("Discord", "https://discord.gg/hnZBzc4NJU")}.`;
}
function createTerminalLink(text: string, url: string) {
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index 283a10349..0cff83892 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -12,7 +12,7 @@ import { handleError } from "../utils/handle-error";
import { highlighter } from "../utils/highlighter";
import { logger } from "../utils/logger";
import { spinner } from "../utils/spinner";
-import { sendTelemetryEvent } from "../telemetry";
+import { sendTelemetryEvent, showTelemetryNoticeIfNeeded } from "../telemetry";
export const initOptionsSchema = z.object({
cwd: z.string(),
@@ -34,6 +34,7 @@ export const init = new Command()
.option("-s, --silent", "mute output.", false)
.action(async (opts) => {
try {
+ showTelemetryNoticeIfNeeded();
const options = initOptionsSchema.parse({
cwd: path.resolve(opts.cwd),
...opts,
diff --git a/packages/cli/src/commands/registry-build.ts b/packages/cli/src/commands/registry-build.ts
index ea9baf9f0..3466c9c52 100644
--- a/packages/cli/src/commands/registry-build.ts
+++ b/packages/cli/src/commands/registry-build.ts
@@ -13,7 +13,7 @@ import { spinner } from "@/src/utils/spinner";
import { Command } from "commander";
import { z } from "zod";
import { REGISTRY_ITEM_SCHEMA_URL } from "../registry";
-import { sendTelemetryEvent } from "../telemetry";
+import { sendTelemetryEvent, showTelemetryNoticeIfNeeded } from "../telemetry";
export const buildOptionsSchema = z.object({
cwd: z.string(),
@@ -48,6 +48,7 @@ export const registryBuild = new Command()
async function buildRegistry(opts: z.infer<typeof buildOptionsSchema>) {
try {
+ showTelemetryNoticeIfNeeded();
const options = buildOptionsSchema.parse(opts);
const [{ errors, resolvePaths, config }, projectInfo] = await Promise.all([
diff --git a/packages/cli/src/commands/telemetry.ts b/packages/cli/src/commands/telemetry.ts
index ba193ee69..57e0124dc 100644
--- a/packages/cli/src/commands/telemetry.ts
+++ b/packages/cli/src/commands/telemetry.ts
@@ -1,4 +1,5 @@
-import { toggleTelemetry } from "@/src/telemetry";
+import { toggleTelemetry, TELEMETRY_DOCS_URL } from "@/src/telemetry";
+import { configStore } from "@/src/telemetry/store";
import { handleError } from "@/src/utils/handle-error";
import { logger } from "@/src/utils/logger";
import { Command } from "commander";
@@ -6,19 +7,43 @@ import { Command } from "commander";
export const telemetry = new Command()
.name("telemetry")
.description(
- "enable or disable the collection of anonymous usage data. If no option is provided, the command enables the collection of anonymous usage data."
+ "manage the collection of anonymous usage data"
)
- .option("--enable", "enable telemetry (default)")
+ .option("--enable", "enable telemetry")
.option("--disable", "disable telemetry")
.action(async (opts) => {
try {
- const enabled = !opts.disable;
+ if (opts.enable && opts.disable) {
+ logger.error("Cannot use --enable and --disable together.");
+ return;
+ }
+
+ // No flags — show current status
+ if (!opts.enable && !opts.disable) {
+ const configEnabled = configStore.get("telemetry_enabled");
+ const envDisabled = process.env.MERCUR_DISABLE_TELEMETRY === 'true';
+ const enabled = configEnabled && !envDisabled;
+ const status = enabled ? "enabled" : "disabled";
+ logger.log(`Telemetry is currently ${status}.`);
+ if (envDisabled && configEnabled) {
+ logger.log(`(Disabled via MERCUR_DISABLE_TELEMETRY environment variable)`);
+ }
+ logger.log(
+ enabled
+ ? `Run "mercurjs telemetry --disable" to opt out.`
+ : `Run "mercurjs telemetry --enable" to opt in.`
+ );
+ logger.log(`Learn more: ${TELEMETRY_DOCS_URL}`);
+ return;
+ }
+
+ const enabled = !!opts.enable;
toggleTelemetry(enabled);
if (enabled) {
- logger.success("Telemetry enabled.");
+ logger.success(`Telemetry enabled. Learn more: ${TELEMETRY_DOCS_URL}`);
} else {
- logger.success("Telemetry disabled.");
+ logger.success("Telemetry disabled. No data will be collected.");
}
} catch (error) {
handleError(error);
diff --git a/packages/cli/src/telemetry/index.ts b/packages/cli/src/telemetry/index.ts
index 878e6656a..96a294905 100644
--- a/packages/cli/src/telemetry/index.ts
+++ b/packages/cli/src/telemetry/index.ts
@@ -5,6 +5,7 @@ import { detectSystemInfo } from "./detect-system-info";
import { getPackageManager } from "../utils/get-package-manager";
import { hashToBase64 } from "./hash";
import { getProjectInfo, type PackageJson } from "../utils/get-project-info";
+import { highlighter } from "../utils/highlighter";
const TELEMETRY_URL = process.env.MERCUR_TELEMETRY_PROXY_URL || 'https://telemetry.mercurjs.com/api/v1/events'
@@ -22,6 +23,31 @@ export const toggleTelemetry = (enabled: boolean) => {
configStore.set("telemetry_enabled", enabled)
}
+export const TELEMETRY_DOCS_URL = 'https://docs.mercurjs.com/v2/telemetry'
+
+export const showTelemetryNoticeIfNeeded = () => {
+ if (configStore.get("notice_shown")) {
+ return;
+ }
+
+ configStore.set("notice_shown", true);
+
+ if (process.env.MERCUR_DISABLE_TELEMETRY === 'true') {
+ return;
+ }
+
+ console.error(
+ [
+ "",
+ "Mercur collects anonymous usage data to improve the CLI experience.",
+ `You can disable this at any time by running: ${highlighter.info("mercurjs telemetry --disable")}`,
+ `Or by setting ${highlighter.info("MERCUR_DISABLE_TELEMETRY=true")}`,
+ `Learn more: ${highlighter.info(TELEMETRY_DOCS_URL)}`,
+ "",
+ ].join("\n")
+ );
+}
+
const isTelemetryEnabled = () => {
return configStore.get("telemetry_enabled") && process.env.MERCUR_DISABLE_TELEMETRY !== 'true'
}
diff --git a/packages/cli/src/telemetry/store.ts b/packages/cli/src/telemetry/store.ts
index 44e966982..6b6fca13b 100644
--- a/packages/cli/src/telemetry/store.ts
+++ b/packages/cli/src/telemetry/store.ts
@@ -1,55 +1,57 @@
-import os from "os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
import { join } from "path";
-
interface TelemetryConfig {
- "telemetry_enabled": boolean;
- "telemetry_email": string | null;
+ telemetry_enabled: boolean;
+ telemetry_email: string | null;
+ notice_shown: boolean;
}
-class ConfigStore {
- private config: TelemetryConfig;
- public path: string = join(os.tmpdir(), "mercur");
+const CONFIG_DIR = join(homedir(), ".mercur");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
- constructor() {
- this.config = this.createBaseConfig();
- }
-
- private createBaseConfig(): TelemetryConfig {
- return {
- "telemetry_enabled": true,
- "telemetry_email": null,
- };
- }
+const DEFAULTS: TelemetryConfig = {
+ telemetry_enabled: true,
+ telemetry_email: null,
+ notice_shown: false,
+};
+class ConfigStore {
get<K extends keyof TelemetryConfig>(key: K): TelemetryConfig[K] {
- return this.config[key];
+ const config = this.read();
+ return config[key];
}
set<K extends keyof TelemetryConfig>(key: K, value: TelemetryConfig[K]): void {
- this.config[key] = value;
- }
-
- all(): TelemetryConfig {
- return this.config;
- }
-
- size(): number {
- return Object.keys(this.config).length;
- }
-
- has(key: keyof TelemetryConfig): boolean {
- return key in this.config && this.config[key] !== undefined;
- }
-
- del(key: keyof TelemetryConfig): void {
- delete this.config[key];
- }
-
- clear(): void {
- this.config = this.createBaseConfig();
+ const config = this.read();
+ config[key] = value;
+ this.write(config);
+ }
+
+ private read(): TelemetryConfig {
+ try {
+ if (!existsSync(CONFIG_PATH)) {
+ return { ...DEFAULTS };
+ }
+ const raw = readFileSync(CONFIG_PATH, "utf-8");
+ const parsed = JSON.parse(raw);
+ return { ...DEFAULTS, ...parsed };
+ } catch {
+ return { ...DEFAULTS };
+ }
+ }
+
+ private write(config: TelemetryConfig): void {
+ try {
+ mkdirSync(CONFIG_DIR, { recursive: true });
+ writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", {
+ mode: 0o600,
+ });
+ } catch {
+ // Silently fail — telemetry config is non-critical
+ }
}
}
export const configStore = new ConfigStore();
-