Telemetry Initialization and Opt-Out#

comfy-cli collects usage analytics via two providers — Mixpanel and PostHog — configured in comfy_cli/tracking.py. Provider objects are instantiated at module import time (lines 189–192), meaning they are created on every comfy invocation, including contexts like shell completion that never execute a real command.

Providers#

Both providers are constructed unconditionally when tracking.py is imported 1:

The PostHog token can be overridden by setting the POSTHOG_API_KEY environment variable 2. Events sent to PostHog are prefixed with cli: (e.g., cli:install) to match a shared surface-prefix convention; Mixpanel keeps bare legacy names for historical continuity 3.

On exit, atexit.register(_flush_all_providers) is called so in-flight PostHog events (which ship asynchronously) are drained before the process terminates 4.

Consent Gate: Three Layers#

All passive telemetry is subject to a three-layer check implemented in _consent_enabled():

1. Environment variables — _telemetry_disabled_by_env() checks DO_NOT_TRACK and COMFY_NO_TELEMETRY. Either variable set to any non-empty, non-"0" value suppresses all telemetry. This follows the Console Do Not Track convention.

2. Persisted config flag — CONFIG_KEY_ENABLE_TRACKING in the user's config file (via ConfigManager) 5. Written by init_tracking(True/False) and inspected by config_manager.get_bool() 6.

3. Session-only tracking — the module-level boolean _session_only_tracking 7. This process-scoped flag captures agentic (non-interactive) usage without persisting consent to disk, so a later interactive human run can still prompt for consent.

The central gate in track_event() enforces all three: env opt-out short-circuits first, then persisted flag or session flag must be truthy.

Consent Prompt Flow#

prompt_tracking_consent() is called from the global CLI callback in cmdline.py on every invocation except comfy setup 8, which owns its own consent wizard:

• Env opt-out present → returns immediately; no prompt, no persistence.
• Consent already recorded (config flag exists) → returns immediately.
• Non-TTY (CI, piped input, agents) → generates and persists a stable anonymous user_id without enabling telemetry. Avoids violating DO_NOT_TRACK spirit for OSS tooling 9.
• Interactive TTY, first run → prompts: "Do you agree to enable tracking?" and calls init_tracking().

init_tracking(True) persists the consent flag, generates a user_id (UUID, stored in config), and fires a one-time install event 10.

To enable or disable tracking manually:

comfy tracking enable
comfy tracking disable

These commands are registered at 11 and exposed via app.add_typer(tracking.app, name="tracking", ...) in cmdline.py 12.

Data Sent and Sanitization#

Every event is enriched with cli_version and tracing_id (a per-invocation UUID) by _dispatch(). Command kwargs are scrubbed before sending via filter_command_kwargs():

• Sensitive names (_token, _api_key, _secret, _password, exact matches like key, prompt, changelog) → value replaced with "<redacted>" 13.
• URL values → query strings and fragments stripped to remove embedded tokens (e.g., CivitAI download links) 14.
• Non-JSON-serializable values and Click ctx/context kwargs → dropped 15.

The @tracking.track_command() decorator applies this automatically to decorated commands.

Special Cases#

User feedback (submit_feedback) is not gated on the consent flag — it is an explicit user-initiated action, so only the env opt-out applies 16. If opted out, it returns False and the caller notifies the user rather than silently dropping the message.

Agent reviews (submit_agent_review) are treated like passive telemetry and are fully consent-gated 17.

Known Gap: No Lightweight Context Optimization#

PostHog and Mixpanel client objects are instantiated at module import time regardless of the command being run. Shell completion, --version, and other trivial invocations all trigger the full provider initialization 1. There is currently no optimization to skip this in lightweight contexts, which means any startup overhead from the telemetry library imports is always paid.

Key Files#