Skip to content

Shared output and rendering options

Shared options control stable user-facing runtime behavior such as:

  • output rendering
  • verbosity
  • diagnostics visibility
  • machine-readable JSON and NDJSON rendering
  • color behavior
  • command applicability behavior and runtime input modes

Note

The canonical vocabulary used throughout the documentation is defined in Terminology and Canonical Vocabulary.

For CLI/configuration/API spelling conventions for multi-word option values, see Configuration discovery, precedence, and policy.

Output format

TopMark supports four stable output formats:

--output-format text        # Interactive terminal-oriented TEXT output (default)
--output-format markdown    # Markdown document output
# Machine-readable formats:
--output-format json        # JSON object (formatted)
--output-format ndjson      # NDJSON records (1 per line)

These formats behave consistently across commands that support machine-readable output.

  • Human-facing output:
  • text (default): intended for interactive terminal use; when color is enabled, output is rendered in color by default (disable with --color never).
  • markdown: document-oriented Markdown output; ignores TEXT-specific verbosity rendering.
  • Machine-readable formats:
  • json: emits a single machine-readable JSON document formatted for readability and tooling.
  • ndjson: emits one machine-readable NDJSON record per line.

TEXT vs machine-readable rendering

TopMark intentionally separates:

  • TEXT-oriented interactive rendering;
  • Markdown-oriented document rendering;
  • machine-readable JSON and NDJSON serialization;
  • process exit-code semantics.

Note

Verbosity, quiet mode and color rendering affect only human-facing TEXT rendering.

Shared output controls (TEXT output)

Color

Color output applies only to the text output format.

--color auto
--color always
--color never
  • auto (default): enable color in interactive terminals
  • always: force color
  • never: disable color

Color has no effect on markdown or machine-readable output formats (json or ndjson).

TopMark also respects the standard NO_COLOR environment variable for TEXT rendering.

Verbosity

TopMark supports verbosity controls for TEXT-oriented human-readable output.

--verbose       # Increase TEXT output verbosity
-v              # Shorthand (can be repeated)

In TEXT output, verbosity affects:

  • diagnostic detail
  • hint visibility and grouping
  • summary rendering
  • CLI progress reporting

Quiet mode

TopMark supports quiet mode for TEXT-oriented human-readable rendering.

--quiet         # Suppress TEXT output (only for supported commands)
-q              # Shorthand

Note:

Exit-code behavior

  • Exit codes are not affected by verbosity or --quiet.
  • --quiet suppresses human-readable rendering while preserving CLI semantic status behavior.

See also:

Note

  • Verbosity (-v / --verbose) affects only TEXT rendering.
  • Quiet mode (-q / --quiet) suppresses TEXT rendering for commands that support it.
  • Markdown and machine-readable output are not affected by TEXT verbosity controls.

Command applicability

TopMark commands expose only options applicable to the selected command family. Known but inapplicable options are rejected as explicit CLI usage errors rather than ignored silently.

Related docs:

Command-family applicability

Command family Applicable controls Inapplicable controls
check File input, filtering, configuration loading, strictness, reporting, diff, --apply, write mode, header generation/update policy, generated-header formatting N/A beyond normal validation conflicts
strip File input, filtering, configuration loading, strictness, reporting, diff, --apply, write mode, shared content-probe runtime policy Header generation/update policy and generated-header formatting
probe File input, filtering, configuration loading, strictness, output format, shared content-probe runtime policy --apply, write mode, diff, human-readable summary/reporting, header generation/update policy, generated-header formatting, stdin option flags (use '-' plus --stdin-filename instead)
config check / config dump Configuration loading, strictness where applicable, output format, and documented configuration overrides File processing, mutation, diff, reporting, positional paths
config defaults / config init Command-specific informational/configuration-scaffolding options Configuration discovery, file processing, mutation, --quiet, positional paths
registry * / version Human-readable informational output controls Configuration discovery, file processing, mutation, --quiet, positional paths

Shared input modes

Runtime file-processing commands (check, strip, and probe) support the same input modes:

  • Path mode: process positional paths and/or paths loaded from --files-from FILE.
  • List STDIN mode: read newline-delimited paths or patterns from STDIN using one of:
  • --files-from -
  • --include-from -
  • --exclude-from -
  • Content STDIN mode: process one virtual runtime file from STDIN content by passing - as the sole PATH and providing --stdin-filename NAME.

These modes are mutually exclusive: do not mix - (content mode) with --files-from -, --include-from -, or --exclude-from - (list mode).

Note

STDIN input

TopMark does not provide a --stdin option flag. Use the POSIX-style - PATH sentinel together with --stdin-filename for content mode.

Passing --stdin is treated as an invalid option and results in a CLI usage error.

In content STDIN mode, --stdin-filename is required so TopMark can resolve file type, processor binding, and path-sensitive policy exactly as it would for a real file path.

For mutation commands (check and strip), --apply in content mode writes transformed content to STDOUT and routes diagnostics to STDERR. This ensures consistent file-type resolution and runtime header-policy evaluation behavior between path-based and STDIN inputs without writing to an unknown filesystem location.

Configuration-loading applicability

Layered configuration loading and discovery behavior apply to check, strip, probe, config check, and config dump.

Layered configuration loading and discovery behavior do not apply to:

See also