Skip to main content

Clerk Telemetry

Clerk collects telemetry data from its SDKs and the Clerk CLI about general product and feature usage. Participation in telemetry collection is optional and users of the product can opt out at any time.

How you are notified

Server-side SDKs (e.g., @clerk/nextjs, @clerk/tanstack-react-start, @clerk/react-router, @clerk/express, @clerk/astro, @clerk/fastify) print a notice in your terminal once each time you start your development server. The notice is skipped in continuous integration (CI) environments and when using a production instance.

Browser-only SDKs do not print a runtime notice. This includes @clerk/clerk-js loaded directly, Vite SPAs using @clerk/react without a server runtime, and the browser-facing surfaces of a Chrome extension (content scripts, popups, options pages). For those setups, this page is the disclosure.

The Clerk CLI prints a notice the first time it runs on a machine and sends nothing during that run. clerk feedback is the exception: it shows the notice, then sends your report and that run's command event. In CI environments, where the CI environment variable is set, the CLI skips the notice and sends from the first run. Shell completion (clerk completion and the helper behind the Tab key) never sends anything.

Why is Clerk collecting telemetry data?

While we actively engage with our users and community to gather feedback and inform our product roadmap, the information collected from these efforts only represents a small subset of our users.

Collecting telemetry data gives us a clearer picture into how our SDKs, components, and authentication helpers are used for a diverse set of problems. This data provides valuable insights to help us prioritize features that are useful and impactful for as many of our users as possible.

What data is being collected?

We track general usage information about our SDKs, components, and authentication helpers from development instances only. While we collect identifiers that allow us to associate events with specific Clerk instances, we do not collect any information from your users. When telemetry is on, the Clerk CLI sends an event for each command it runs, whichever instance the command acts on, and clerk feedback sends the report you write. See Clerk CLI.

Examples of data we are interested in:

  • How often are our different components (<SignIn />, <SignUp />, <UserProfile />) rendered?
  • What props are being used?
  • How are developers utilizing the appearance prop on our components?
  • What versions of our SDKs are being used?
  • What associated framework versions are being used? (e.g., what next version is being used along with @clerk/nextjs)
  • Usage of new features

Note

We regularly audit this list to ensure it is an accurate representation of the data we are collecting. To audit telemetry data sent from our SDKs yourself, you can set a CLERK_TELEMETRY_DEBUG=1 environment variable in your application. In this mode, telemetry events are only logged to the console and not sent to Clerk. The Clerk CLI doesn't read this variable. Run a CLI command with --verbose instead, and the CLI prints each event before it sends it.

An example event looks like this:

{
  event: 'COMPONENT_MOUNTED',
  cv: '4.62.1',
  sdk: '@clerk/nextjs',
  sdkv: '4.25.6',
  pk: 'pk_test_YmFsYW5jZWQtY293YmlyZC0xNi5jbGVyay5hY2NvdW50cy5kDXyk',
  payload: { component: 'SignIn', appearanceProp: false },
}
  • event — A unique identifier for the event type.
  • cv — Clerk Version. The version of the core Clerk library in use.
  • sdk — SDK. The Clerk SDK that is being used.
  • sdkv — SDK Version. The version of the Clerk SDK.
  • pk — Publishable Key. The instance's .
  • payload — Each unique event can provide custom data as part of the payload. As seen above, for the COMPONENT_MOUNTED event we track the component name and additional data about prop usage.

Clerk CLI

While telemetry is on, the Clerk CLI sends one CLI_COMMAND_EXECUTED event each time a command runs, apart from the runs listed in How you are notified. The event records how you use the CLI. It doesn't include command arguments, option values, file paths, secret keys, or data about your users.

FieldDescription
commandThe command path, such as users list. Arguments aren't included.
flagsThe names of the flags you set. Their values aren't included.
outcome, exit_code, error_codeHow the command ended.
stageHow far a multi-step command got. Set by clerk init, clerk auth login, clerk deploy, and clerk deploy status. clerk link and clerk doctor --fix also set it when they need to sign you in. Other commands send null.
pause_step, componentsThe step a deploy paused on, and which of DNS, SSL, email DNS, and OAuth credentials were verified. clerk deploy sets both, and clerk deploy status sets components. Other commands send null values.
duration_msHow long the command ran.
machine_uuidA random ID the CLI generates and stores on your machine.
install_method, ai_agent, terminal_program, mode, os, arch, ci, in_tmux, in_screenThe environment the CLI ran in, such as how you installed it and whether an AI agent ran the command.
envThe Clerk API environment the CLI talks to.
workspace_id, app_idThe application ID of the project the current directory is linked to, and its workspace ID when the CLI has one.

An example event looks like this:

{
  "sdk": "clerk-cli",
  "sdkv": "4.1.0",
  "event": "CLI_COMMAND_EXECUTED",
  "payload": {
    "command": "users list",
    "flags": "limit",
    "outcome": "success",
    "exit_code": 0,
    "error_code": null,
    "stage": null,
    "pause_step": null,
    "components": { "dns": null, "ssl": null, "mail": null, "oauth": null },
    "duration_ms": 412,
    "machine_uuid": "00000000-0000-0000-0000-000000000000",
    "install_method": "homebrew",
    "ai_agent": "",
    "terminal_program": "ghostty",
    "mode": "human",
    "os": "darwin",
    "arch": "arm64",
    "ci": false,
    "in_tmux": false,
    "in_screen": false,
    "env": "production",
    "workspace_id": "",
    "app_id": "app_123abc"
  }
}

Feedback reports

While telemetry is on, clerk feedback sends a CLI_FEEDBACK event with:

  • The report you write: what you tried to do (goal), what you ran (attempted), what went wrong (issue), and how it ended (outcome)
  • If you add them, the command involved (command), the error text and code (error_text, error_code), and a suggestion (suggestion)
  • A report ID, source: "cli", and the number of replacements the scrubbing made
  • The same machine and environment fields as a command event, from machine_uuid to app_id in the field table

Before the report leaves your machine, the CLI replaces common secret formats with [REDACTED], home directory paths with ~, and email addresses with [EMAIL], on a best-effort basis. Run clerk feedback --dry-run to see the exact report without sending it. The CLI still sends the run's command event, except on a first run outside CI.

Clerk staff with access to the telemetry warehouse can read feedback reports. To have a report deleted, contact Clerk support with the report ID the CLI prints after it sends the report.

What about sensitive data?

We will not collect sensitive data from your application or development environment that is not directly related to your implementation of Clerk's SDKs. Notably, we will not collect: environment variables unrelated to Clerk, any information about your users, file paths, contents of files, logs, git remote information, or raw JavaScript errors. This covers the SDKs and the Clerk CLI's command events. A clerk feedback report holds the text you write in it, after the scrubbing described in Feedback reports.

How is my data protected?

Clerk takes data privacy and protection seriously. Telemetry data is most useful in aggregate form to gain product insights, and the raw data is only available to a small subset of Clerk employees.

We will never share with or sell telemetry data to third parties. The data is used strictly to help improve the Clerk product.

How do I opt out?

Environment variables

Warning

Note that the variable name might differ between frameworks. See the framework specific instructions below.

For meta-framework SDKs, you can opt out of telemetry collection by setting the environment variable:

.env
CLERK_TELEMETRY_DISABLED=1

telemetry prop

If you are using @clerk/react directly, or using an SDK that doesn't have environment variable support, you can opt out by passing the telemetry prop to <ClerkProvider>:

<ClerkProvider telemetry={false} />

Framework specific instructions

.env
NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED=1
<ClerkProvider telemetry={false} />
const clerk = new Clerk(publishableKey)
c.load({ telemetry: false })
<ClerkProvider telemetry={false} />
<ClerkProvider telemetry={false} />
.env
PUBLIC_CLERK_TELEMETRY_DISABLED=1
.env
VITE_CLERK_TELEMETRY_DISABLED=1
.env
VITE_CLERK_TELEMETRY_DISABLED=1

For the Clerk CLI

To opt out of Clerk CLI telemetry on your machine, run:

terminal
clerk telemetry disable

clerk telemetry status shows whether telemetry is on and, when it's off, why. clerk telemetry enable removes the opt-out.

To opt out with an environment variable instead, export CLERK_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 in your shell. The CLI doesn't read them from a .env file. Any value other than an empty string, 0, or false (case-insensitive) opts out, and either variable opts out even after you run clerk telemetry enable. Opting out also removes the AIAgent/<name> part of the User-Agent header the CLI sends with its HTTP requests, and turns off clerk feedback, which prints the GitHub issues URL instead.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub