Invocation, options and results
Linktopaz fmt
topaz fmt [entry]
Input
Accept zero or one entry operand. With no entry, select the package under - or the current directory. With an entry, use the selected entry and source root.
Accept the listed compiler, verbosity, root, language, resource, and - options. Reject -, -, build selectors, unknown options, repeated options, and malformed values.
Read each selected source as UTF-8 and require valid syntax. Before write mode starts replacing files, validate every formatted replacement with the same language mode and selected parser.
Options and conflicts
| Option | Default | Contract | Conflicts |
|---|---|---|---|
--compiler rust|self | self | compiler selector (default self); rust selects the reference compiler Also rejects combination with --producer, --self-source. | None listed |
--check | false | fmt only: report formatting drift without writing source or metadata | None listed |
--verbose | false | Reports the selected compiler and whether it was explicit or the default. For | None listed |
--root <dir> | entry directory; . in package mode | The explicit source root or package root for this invocation. | None listed |
--language-version <5.21> | 5.21 | language version selector | None listed |
--compiler-memory-mib <MiB> | 8192 | self compiler worker memory budget (8192); overrides TOPAZ_COMPILER_MEMORY_MIB A positive integer is required. Environment input: TOPAZ_COMPILER_MEMORY_MIB. | None listed |
--compiler-time-ms <ms> | 1800000 | self compilation wall-clock budget (1800000); overrides TOPAZ_COMPILER_TIME_MS A positive integer is required. Environment input: TOPAZ_COMPILER_TIME_MS. | None listed |
Output channels
stdout
stderr
Exit status
0
Every selected file is formatted successfully or check mode finds no formatting drift.
1
Arguments, input, syntax, generated formatting, or writing fails, or check mode finds drift.
Effects
Check mode writes no source or package metadata. Write mode changes selected source files in place after all planned output parses. An I/O failure during replacement can leave earlier files formatted and later files unchanged.
Package traversal sorts entries by native filename order, formats regular . files, and skips ., ., target, node_, and vendor directories. It skips file and directory symlinks during that traversal. An explicit file operand selects one file directly. Formatting does not rewrite manifests and locks.
Formatting performs no network access and does not materialize dependencies.
With the same file set and source bytes, language mode, formatter version, and host filename ordering, formatted bytes and traversal order are deterministic. Formatting an already formatted file leaves it unchanged. Nonempty output uses LF line endings and one final newline.
Package selection supplies the source root and language mode. Formatting does not resolve versions, refresh the lock, or format vendored dependencies.
Operation
LinkUse the check mode to detect formatting changes before writing them. Package mode selects eligible source files and skips vendor and target trees.
Option conditions
Link- cannot be combined with bootstrap - or -
- applies to fmt only
Behavior contract
LinkCommand behavior
Arguments and rejection
Accept zero or one entry operand. With no entry, select the package under - or the current directory. With an entry, use the selected entry and source root.
Accept the listed compiler, verbosity, root, language, resource, and - options. Reject -, -, build selectors, unknown options, repeated options, and malformed values.
Read each selected source as UTF-8 and require valid syntax. Before write mode starts replacing files, validate every formatted replacement with the same language mode and selected parser.
Output
Standard output is empty. Standard error lists paths with formatting drift in check mode and gives the number of files checked and changed. Write mode reports the number formatted and changed.
Errors use standard error. - is rejected. A human progress or summary line is not a source file.
Exit status
Exit 0 means write mode completed all replacements or check mode found no drift. Exit 1 covers drift in check mode, invalid arguments, input or package errors, invalid source, invalid formatted output, and write failures.
Filesystem effects
Check mode writes no source or package metadata. Write mode changes selected source files in place after all planned output parses. An I/O failure during replacement can leave earlier files formatted and later files unchanged.
Package traversal sorts entries by native filename order, formats regular . files, and skips ., ., target, node_, and vendor directories. It skips file and directory symlinks during that traversal. An explicit file operand selects one file directly. Formatting does not rewrite manifests and locks.
Network access
Formatting performs no network access and does not materialize dependencies.
Reproducibility
With the same file set and source bytes, language mode, formatter version, and host filename ordering, formatted bytes and traversal order are deterministic. Formatting an already formatted file leaves it unchanged. Nonempty output uses LF line endings and one final newline.
Packages and locks
Package selection supplies the source root and language mode. Formatting does not resolve versions, refresh the lock, or format vendored dependencies.
Why
Formatting and checking formatting express different intents. The check option preserves a read-only inspection path, while validating every replacement before writing prevents malformed output from corrupting source.
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/compiler_support.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 covers JSON-selector rejection. Check-only drift and successful source rewrites are outside its exact argument vector and remain not-run.
Example contract
LinkExample contract
The invocation topaz fmt main. is expected to exit with 1.
This command does not provide a JSON report format. The invocation is rejected during argument validation before processing the program.
Why
This command does not provide a JSON report format. Rejecting the option prevents a successful exit from silently ignoring the requested output format.
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/compiler_support.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.
This command does not provide a JSON report format. The invocation is rejected during argument validation before processing the 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/compiler_support.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. 3 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.