Feature request: add a non-mutating `buzz doctor` command
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**Motivation**
The CLI has comprehensive command help, but `--help` cannot answer whether a Buzz environment is actually ready to use. Today, troubleshooting usually means running a real command and interpreting the first error it returns.
A single safe preflight would help humans, agents, automation, and support reports answer:
- Is the local configuration present and parseable?
- Which public identity will sign requests?
- Is the relay reachable and does it return valid NIP-11 metadata?
- Is authentication accepted?
- Is the identity a member of the selected community?
Buzz Desktop has a Doctor surface for managed ACP runtimes, but that has a different scope and is unavailable in headless environments, containers, and servers.
**Proposed solution**
Add a root-level `buzz doctor` command that runs independent checks, aggregates the results rather than failing at the first problem, and never publishes events or changes local or remote state.
A useful first slice could include:
Local checks, available even with `--offline`:
- CLI version/build information
- relay URL presence, syntax, and canonicalization
- `BUZZ_PRIVATE_KEY` presence and parseability, reporting only the derived public identity
- `BUZZ_AUTH_TAG` syntax and basic consistency, without ever printing the tag
Read-only remote checks:
- DNS/TLS/network reachability
- NIP-11 retrieval and basic compatibility
- authenticated read access
- community membership and available role/scope information
- WebSocket connection or subscription readiness, without publishing an event
The command should use the existing global relay, key, auth-tag, and output-format options. Default structured output could follow the existing CLI convention, for example:
```json
{
"status": "warning",
"checks": [
{
"id": "identity",
"status": "ok",
"message": "Signing identity is available"
},
{
"id": "relay",
"status": "error",
"message": "Relay is unreachable",
"remediation": "Check the relay URL and network connectivity"
}
]
}
```
Required behavior:
- Running with missing or invalid credentials reports those as check results instead of failing during CLI argument parsing.
- `--offline` runs only local checks and clearly marks remote checks as skipped.
- Remote probes are read-only.
- All applicable checks run so one invocation can reveal multiple problems.
- Output and error messages never expose private keys, auth tags, bearer values, or signed request material.
- Check identifiers and structured fields are stable enough for automation.
- Exit behavior distinguishes a failed required check from warnings while preserving structured output. I would welcome maintainer guidance on whether warnings should still exit zero and how this should map onto the existing exit-code categories.
Suggested coverage:
- unit tests for aggregation, redaction, skipped checks, and exit precedence
- mocked relay tests for unreachable, malformed NIP-11, unauthenticated, and non-member cases
- a CLI-definition test proving `doctor --help` remains available without credentials
For the initial version, local configuration plus NIP-11, read-only authentication, and membership checks may be enough; WebSocket readiness could follow separately if it adds too much scope.
**Alternatives considered**
- Run a harmless existing read command such as `channels list`: this fails fast, does not cover local configuration, and can blur network, authentication, and membership failures.
- Use the Desktop Doctor: it diagnoses managed agent runtimes rather than CLI-to-community readiness and is not available headlessly.
- Use shell scripts and `curl`: these duplicate Buzz signing/authentication behavior and make secret handling less reliable.
- Improve individual error messages only: useful, but it does not provide proactive, aggregated readiness information.
**Additional context**
- The prior Doctor issue, #76, was specifically for the Desktop ACP setup surface and was completed by #80.
- PR #2933 proposes `buzz users me` with a `whoami` alias. A doctor command should reuse the same local identity derivation if that lands, not introduce a competing identity command.
- I searched open and closed issues and PRs for `doctor`, `diagnostic`, `health check`, `preflight`, and `troubleshoot`; I found no existing CLI diagnostics proposal.
- A local audit of current `main` found that `--help` succeeds across all exposed CLI command paths, so this proposal is about runtime readiness rather than help coverage.
Contributor guide
Assessment
This issue has not been assessed yet.