[SophiaHuangCc]

What

Support hyperframes telemetry status --json, returning enabled, source, configPath, statePath, and commandCount.

Why

Agents and scripts currently receive exit code 2 and json_unsupported when requesting telemetry status as JSON. They must parse the human-readable output to determine whether telemetry is enabled.

With this change, the command exits 0 and prints one JSON object. For example, an isolated test configuration with seven tracked commands and DO_NOT_TRACK=1 returns the following fields (paths vary by configuration directory).

{
  "enabled": false,
  "source": "DO_NOT_TRACK",
  "configPath": "/tmp/hf-telemetry-example/config.json",
  "statePath": "/tmp/hf-telemetry-example/install-state.json",
  "commandCount": 7
}

Related work

Fixes #7275.

No competing implementation was found when checking the issue discussion and related PRs. The branch is rebased onto upstream main 6abc62a17.

How

• Declare --json through the existing shared command factory so the CLI guards and agent-mode contract discover it automatically.
• Serialize the fresh configuration and existing effective-status policy, so environment and build overrides determine enabled and source consistently with human output.
• Restrict --json to status. Other telemetry operations return a usage error before changing preferences.
• Document the flag and output fields in the CLI reference.

Test plan

Using Bun 1.4.4 and Node.js 22.23.3, run from the repository root.

bun run build
bun run --cwd packages/cli test src/commands/telemetry.test.ts src/telemetry/policy.test.ts src/cli.agentMode.test.ts
bun run --cwd packages/cli typecheck

• All 554 tests pass, including the unchanged agent-mode contract suite.

• Six new JSON cases check all five fields for saved enabled/disabled preferences, both environment opt-outs, development mode, and a telemetry-disabled build. Three additional cases reject JSON for other operations. All nine fail against the original implementation and pass with the fix.

• The built CLI was exercised with isolated temporary settings for JSON output, DO_NOT_TRACK, human output, and rejection of enable --json without changing preferences.

• Repository lint, formatting, Fallow audit against upstream main, comment checks, and test reachability pass. Mintlify validation and broken-link checks pass.

• Unit tests added/updated

• Manual testing performed

• Documentation updated (if applicable)

• Comments follow CONTRIBUTING.md "Comments": they say why, not what, and a bug fix says what the code must do and how to reproduce the bug

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 7cfa296.

Approve preview

[jrusso1020]

Reviewed at 14506ad8848b36aec3a1b2062b7af2cb865152fe.

The JSON status reuses the same effective telemetry policy and fresh configuration as human output (packages/cli/src/commands/telemetry.ts:56). It returns exactly the five requested fields and rejects JSON for mutating operations before writing preferences. The CLI docs describe the supported form.

Validation at this head: bun run --cwd packages/cli test src/commands/telemetry.test.ts src/telemetry/policy.test.ts src/cli.agentMode.test.ts → 554 passed. Full build at this head passed. Fresh independent source review found no Important defect; no live browser or native Windows run. No prior substantive reviews or inline comments were present.

Need: yes, requested starter issue · Size: ok · Reuse: existing CLI policy, color and checker helpers · Simpler: already minimal · Structure: fine
Risk: low — bounded CLI output/checker change

— hf-review

Verdict: APPROVE
Reasoning: The requested behavior is covered by focused tests and reuses the existing contract. No Important blocker found.