Invocation, options and results
Linktopaz explain
topaz explain <TPZ####>
Input
Supply exactly one recognized diagnostic code with the TPZ prefix and four decimal digits. Reject missing, extra, malformed, and unknown codes.
Accept - or -, with human output by default. Reject -, source operands, compiler selectors, and other options.
Options and conflicts
| Option | Default | Contract | Conflicts |
|---|---|---|---|
--format human|json | human | Selects human output or one JSON report. The default is human output. | None listed |
Output channels
stdout
stderr
Exit status
0
The installed catalog contains the code and its report is printed.
1
Arguments, code lookup, or report output fails.
Effects
Read the installed diagnostic catalog. Do not open a program source, create files, or change package metadata.
The explanation comes from the installed catalog without network access.
The same installed catalog, code, output format, and presentation settings produce the same report. Catalog changes between releases can change explanation prose.
No package discovery, dependency resolution, lock validation, or lock update is performed.
Operation
LinkUse the code reported by the compiler. Diagnostic pages define causes and repairs. This command defines how to retrieve the explanation.
Option conditions
LinkUse - for the JSON report. The - spelling is rejected.
Behavior contract
LinkCommand behavior
Arguments and rejection
Supply exactly one recognized diagnostic code with the TPZ prefix and four decimal digits. Reject missing, extra, malformed, and unknown codes.
Accept - or -, with human output by default. Reject -, source operands, compiler selectors, and other options.
Output
Human output contains the code, phase, title, summary, reason, and suggested repairs. JSON output is one object on standard output with string code, phase, title, summary, and why, array fixits of strings, and object machine describing the diagnostic's machine identity.
A runtime machine identity includes its string kind when defined. Failures use standard error and produce no successful explanation object.
Exit status
Exit 0 means the requested code was found and its explanation was printed. Exit 1 means invalid arguments, an unknown code, or an output failure.
Filesystem effects
Read the installed diagnostic catalog. Do not open a program source, create files, or change package metadata.
Network access
The explanation comes from the installed catalog without network access.
Reproducibility
The same installed catalog, code, output format, and presentation settings produce the same report. Catalog changes between releases can change explanation prose.
Packages and locks
No package discovery, dependency resolution, lock validation, or lock update is performed.
Why
A diagnostic explanation describes an installed code independently of a source file. Rejecting an unknown code prevents an empty success from being mistaken for an explanation.
Source evidence
- compiler/crates/topaz_cli/src/command/flags.rs at
b48527d0a174 - compiler/crates/topaz_cli/src/command/dispatch.rs at
b48527d0a174 - compiler/crates/topaz_cli/src/command/validation.rs at
b48527d0a174
The linked public CLI recipe checks the exact displayed argument rejection before the requested operation. It does not execute the successful operation or verify its effects.
The safe recipe rejects the source filename supplied in place of a diagnostic code. Successful human and JSON explanations need different operands and remain outside that recipe.
Example contract
LinkExample contract
The invocation topaz explain main. is expected to exit with 1.
Reject the non-code fixture operand because diagnostic lookup requires a TPZ#### code. No diagnostic explanation is claimed by this example.
Why
Diagnostic codes identify causes independently of source filenames. Rejecting a filename prevents a failed lookup from appearing to explain a program.
Source evidence
- compiler/crates/topaz_cli/src/command/flags.rs at
b48527d0a174 - compiler/crates/topaz_cli/src/command/dispatch.rs at
b48527d0a174 - compiler/crates/topaz_cli/src/command/validation.rs at
b48527d0a174
Example
LinkArgument-rejection example
Linkfunction identity<T>(value: T) -> T {value}
Expected result
Expected result
Textual rejection details remain Pending in the reference model. The independent Tools example gate expects exit 1.
Reject the non-code fixture operand because diagnostic lookup requires a TPZ#### code. No diagnostic explanation is claimed by this example.
Source evidence
- compiler/crates/topaz_cli/src/command/flags.rs at
b48527d0a174 - compiler/crates/topaz_cli/src/command/dispatch.rs at
b48527d0a174 - compiler/crates/topaz_cli/src/command/validation.rs at
b48527d0a174
Verification scope
LinkObserved with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 1. 4 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.