[tigh-latte]

Usage telemetry stack, part 4 of 9. Builds on #570. Next: #572.

Description

This PR wires usage telemetry into the CLI. A hook on the root command records facts from the Click context, and AliasGroup.main hands them to the sender from #570 when the run ends. New commands and flags show up in telemetry with no telemetry code.

• usage_capture.py records the command path, parameter names and where each value came from, the typed flag spellings and aliases, the login method and the API status. It records names defined in code only, never values. Grouped short options (-vS, -vPname) are split up as Click does, so a typed -S or -P always reaches the send checks.
• config_sources.py reports which config or credentials file and profile set a setting, by setting name only.
• handle_api_exceptions records the HTTP status of a handled API error.
• The credential helper commands and login now use the tracked command classes, so their runs are recorded or excluded the same way as every other command.

Behaviour changes

• At the end of every command the CLI now runs the send checks from feat(ENG-15367): add the usage sender and the end-of-run send rules #570. It only builds and sends an event when a project key is set, which this stack never does. Without a key, released builds make no network call and print nothing new.
• When a key is set, the first interactive run prints the notice from feat(ENG-15367): add the usage event, install identity and first-run notice #569 on stderr and sends nothing. Sending starts on the next run. CI sends from the first run.
• test_startup_imports.py now also fails if cloudsmith_cli.core.usage loads at startup. The usage code only loads at the end of a run.

How to try it

CLOUDSMITH_TELEMETRY=log CLOUDSMITH_TELEMETRY_POSTHOG_KEY=phc_dummy cloudsmith --version

Output on stderr

[telemetry] would send (log mode, nothing sent):
{
  "distinct_id": "31b023d1-966a-4fb2-a60d-3e17af367674",
  "event": "cli command executed",
  "properties": {
    "$geoip_disable": true,
    "$process_person_profile": false,
    "aliases_used": [],
    "arch": "arm64",
    "channel": "uv-pip",
    "ci": false,
    "cli_version": "1.30.0",
    "command": "<root>",
    "duration_ms": 207,
    "environment": "development",
    "envvars": [],
    "exit_code": 0,
    "first_run": true,
    "flags": [
      "version"
    ],
    "flags_typed": [
      "--version"
    ],
    "install_id_persisted": true,
    "os": "Darwin",
    "os_version": "25.6",
    "outcome": "success",
    "output_format": "pretty",
    "persona": "human",
    "python_version": "3.14",
    "sample_rate": 100,
    "schema_version": 1,
    "stdout_tty": false
  },
  "timestamp": "2026-10-26T11:56:11.787694+00:00"
}

outcome is one of success, help, usage_error, click_error, api_error, error_exit, aborted or unexpected_error. exit_code is the raw value the process exits with today.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

N/A: there are no user-facing changes while no project key is set.

🤖 Generated with Claude Code