Telemetry

Archgate collects anonymous usage data to help us understand how the CLI is used, prioritize features, and fix crashes. This page explains exactly what is collected, what is not, and how to opt out.

What we collect

Usage analytics (PostHog)

When you run an Archgate command, we record:

• Command name and which flags were used (e.g., check --json — only flag presence, never flag values)
• Exit code (0, 1, 2, or 130) and execution duration (milliseconds), plus a short outcome tag (success, user_error, internal_error, cancelled)
• Environment: OS, architecture, Bun version, Archgate version, CI detection (including provider: GitHub Actions / GitLab CI / CircleCI / etc.), TTY detection, WSL detection, shell (bash, zsh, pwsh…), and locale
• Install context: how the CLI was installed (binary, proto, local dev dependency, or global package manager)
• Project context: whether an Archgate project exists in the current directory, how many ADRs it has, how many have automated rules, and how many distinct ADR domains are used
• Repo context (non-identifying): whether the current directory is a git repository, the host bucket (github / gitlab / bitbucket / azure-devops / other), a hashed repo_id (SHA-256 of the normalized remote URL, truncated to 16 hex characters — not reversible), and the default branch name
• Coarse location: country and region (resolved server-side from your IP, then the IP is discarded — see IP anonymization)
• Anonymous install ID: a random UUID generated on first run — not derived from any personal data

In addition to the general command lifecycle events (command_executed / command_completed), specific commands send enriched outcome events:

• check: aggregate rule counts (total, passed, failed, warnings, errors), output format used, whether filters were applied, files scanned, load duration, check duration — no file paths or violation content
• init: editor choice, whether the plugin was installed, whether the project already existed. A separate one-time project_initialized event is emitted with the repo host bucket, repo_is_git, and a repo_public flag. For repos confirmed public on GitHub / GitLab / Bitbucket, this event also carries the remote URL, owner, and repo name — see Repo identity. Private and self-hosted repos never have identity shared.
• upgrade: version transition (from → to), install method, success/failure, and an optional failure reason
• login: subcommand used (login, logout, refresh, status), success/failure, and a failure bucket (network, tls, denied, other) when it fails
• telemetry_preference_changed: fires once when you enable or disable telemetry, so we can understand opt-out rates

Repo identity

Archgate sends a hashed repo_id with every event so we can count distinct repositories using the CLI without learning their names. The raw remote URL, owner, and repository name are not included in the common event stream.

On archgate init, a one-time project_initialized event is emitted. If — and only if — the repository is confirmed public on GitHub, GitLab, Bitbucket, or Azure DevOps (via an unauthenticated API probe against the host), that event additionally includes remote_url, repo_owner, and repo_name. This lets us see which public repositories are adopting Archgate without ever exposing private ones.

What’s never shared:

• Private repositories (API probe returns 404, 401, or private: true)
• Self-hosted Git hosts (the probe skips these entirely)
• Repositories where the probe times out, is rate-limited, or otherwise fails to return a definitive public answer

Don’t want the event at all? Disable telemetry entirely — the whole project_initialized event is then suppressed along with everything else:

# Per-shell / per-invocation
export ARCHGATE_TELEMETRY=0

# Or persistently
archgate telemetry disable

See How to opt out below for the full details.

Error tracking (Sentry)

When the CLI crashes (exit code 2), we send:

• Error type, message, and stack trace (file paths are stripped to relative paths like src/cli.ts)
• Runtime context: OS, architecture, Bun version, Archgate version
• Anonymous install ID (same random UUID as analytics)

What we do NOT collect

• No personal information: no usernames, emails, or IP addresses. GitHub / GitLab / Bitbucket owner/repository names are only sent on the one-time project_initialized event for repositories that are confirmed public by their host — see Repo identity. Private and self-hosted repos never have identity shared.
• No file content: no ADR content, source code, or file paths
• No prompt or AI context: nothing from agent interactions, prompts, or AI-generated content
• No flag values: we record that --json was used, not what the JSON output contained
• No network activity: no URLs, API keys, or tokens

IP anonymization

Archgate uses PostHog’s built-in IP anonymization:

1. Your CLI sends an event to PostHog with $ip: null
2. PostHog resolves your IP to a country and region (e.g., “US”, “California”) server-side
3. The IP address is then discarded — it is never stored in PostHog

For Sentry error tracking, the project has “Prevent Storing of IP Addresses” enabled, so IPs are stripped before storage.

How to opt out

You can disable all telemetry (both analytics and error tracking) in two ways:

Environment variable

export ARCHGATE_TELEMETRY=0

Accepted values: 0, false, no, off (case-insensitive).

Add this to your shell profile (.bashrc, .zshrc, etc.) to disable permanently.

CLI command

archgate telemetry disable

To re-enable:

archgate telemetry enable

To check current status:

archgate telemetry status

The environment variable takes precedence over the CLI setting. If ARCHGATE_TELEMETRY=0 is set, telemetry is disabled regardless of the CLI config.

Where data is stored

• Analytics: PostHog Cloud (US region). Data retained per PostHog’s standard retention policy.
• Error tracking: Sentry Cloud (US region). Error events retained for 90 days.
• Local config: ~/.archgate/config.json stores your telemetry preference and anonymous install ID.

Open source

The telemetry implementation is fully open source. You can inspect exactly what data is collected by reading:

• src/helpers/telemetry.ts — PostHog event tracking
• src/helpers/sentry.ts — Sentry error capture
• src/helpers/telemetry-config.ts — Config and opt-out logic