Skip to main content

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 — . The instance's Publishable Key.
  • 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. clerk migrate makes three exceptions. It sends the name of the built-in source or platform the users come from, or custom. It also sends the ID of the instance it acts on, whether you name it with flags or the CLI finds it from your linked project or secret key. An application you pass with --app goes out as app_id.

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, clerk deploy status, clerk migrate import, clerk migrate export, and clerk migrate undo. 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.
instance_idThe ID of the Clerk instance a clerk migrate command acted on. Other commands send null, and so does a clerk migrate run that never reaches an instance: sources, runs without a run ID, or an export from a platform other than Clerk. A run that stops before it finds its target sends null only when it has no --instance ID. When Clerk can't name the instance behind a secret key, the CLI labels it on your machine with a hash of the key and sends null. The CLI doesn't send the hash.
migrate_sourceThe built-in source or export platform a migration's users come from, such as auth0 or supabase. A source you wrote sends custom, never its path or name. Other commands send null, and so do sources, runs without a run ID, and a run that stops before it knows the source.
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 ID of the application the command acted on, such as one you pass to clerk migrate with --app. A command that doesn't name an application sends the linked project's. When clerk migrate has no application ID, a run on an instance the CLI can't tie to the linked project sends null. The CLI sends a workspace ID only for the linked project's application.

An example event looks like this:

{
  "sdk": "clerk-cli",
  "sdkv": "4.2.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,
    "instance_id": null,
    "migrate_source": null,
    "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} />
.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> and migrate parts of the User-Agent header the CLI sends with its HTTP requests, and turns off clerk feedback, which prints the GitHub issues URL instead. The CLI adds migrate to the Backend API requests clerk migrate sends, except on a first run outside CI.

Feedback

What did you think of this content?

Last updated on