Skip to content

topmark config dump

Purpose: Dump the effective runtime configuration used by TopMark.

The config dump subcommand (part of topmark config) prints the effective runtime configuration as TOML after applying built-in defaults, discovered project/user configuration files, and CLI overrides.

During loading, TopMark first performs whole-source TOML validation before layered configuration merging and runtime applicability evaluation. Only validated layered configuration fragments contribute to the final runtime output.

It is file-agnostic: it does not resolve or process any files.

Note

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

File type identifier semantics

TopMark accepts file type identifiers in local form, such as python, or qualified form, such as topmark:python.

Local identifiers are accepted only when unambiguous. Internally, TopMark normalizes identifiers to canonical qualified file type identities before filtering, runtime resolution, policy evaluation, diagnostics, and registry lookup.

See file-type filtering for the full identifier contract.

Quick start

# Dump effective configuration (TOML)
topmark config dump

# Honor include/exclude patterns and pattern files
topmark config dump --exclude .venv --exclude-from .gitignore

# Honor patterns from STDIN
printf "*.py\n" | topmark config dump --include-from -

# Suppress TEXT rendering and rely on the exit code
topmark config dump --quiet

# Render document-oriented Markdown output
topmark config dump --output-format markdown

Behavior details

  • Shows the effective runtime configuration (defaults ⟶ discovered configuration ⟶ --config files ⟶ CLI flags), after per-source TOML validation.

  • With --show-layers, also shows the layered configuration provenance before the flattened effective runtime configuration.

  • File-agnostic:

  • Positional PATHS are not accepted (the command fails if provided).

  • --files-from is accepted for compatibility, but listed paths do not affect the dumped configuration.

  • Filters are configuration:

  • --include, --exclude are honored.

  • --include-from / --exclude-from are honored.

  • --include-from - / --exclude-from - read patterns from STDIN.

  • Output is plain TOML. In TEXT rendering, when run with higher verbosity (e.g., -v), the TOML is wrapped between BEGIN/END markers for easy parsing. Markdown output is document-oriented and ignores TEXT-oriented verbosity and quiet controls:

\# === BEGIN[TOML] ===

...TOML...

\# === END[TOML] ===

Layered provenance output (--show-layers)

When --show-layers is used, config dump emits two TOML documents in sequence:

  1. A layered provenance export describing how configuration was constructed.
  2. The final flattened effective runtime configuration (unchanged default behavior).

The layered provenance export is inspection-oriented and uses an array-of-tables structure:

[[layers]]
origin = "<defaults>"
kind = "default"
precedence = 0

[layers.toml.config]
strict = false

Each layer includes:

  • origin - where the configuration came from (e.g. <defaults>, file path)
  • kind - layer type (e.g. default, discovered)
  • precedence - merge order
  • scope_root - optional root for discovered configs
  • toml - the source-local TopMark TOML fragment after TOML-layer validation

The second TOML document is identical to the standard flattened runtime configuration output.

TopMark resolves configuration from defaults, user config, the project chain, explicit --config files, and CLI overrides before staged validation produces the effective runtime configuration. See Configuration discovery, precedence, and policy for the full configuration-loading and validation contract.

Configuration and policy override values shown by this command are part of the stable public configuration surface. Internal implementation details are not part of the user-facing CLI or Python API compatibility contract.

Input applicability

  • List on STDIN for patterns: --include-from - or --exclude-from - read newline-delimited patterns from STDIN. When using -, STDIN must be piped; otherwise the command fails.
  • Content on STDIN (- as PATH) is not supported by config dump. This mode is only meaningful for file-processing commands (for example, check, strip, and probe). --stdin-filename does not apply.
  • --files-from is accepted for compatibility, but listed paths do not affect the dumped configuration. File lists are inputs for file-processing commands, not runtime configuration state.

Positional PATH arguments are rejected as invalid CLI usage. config dump explains configuration state; it does not process source files.

Command-specific options

Option Description
--config Merge an explicit TOML configuration file (can be repeated).
--no-config Do not discover local project/user configuration file.
--include Add include patterns (can be repeated).
--exclude Add exclude patterns (can be repeated).
--include-from Read include patterns from file (one per line, # comments allowed).
--exclude-from Read exclude patterns from file (one per line, # comments allowed).
--files-from Accept a file-list input for compatibility; listed paths do not affect the dumped configuration.
--file-type Restrict to local or qualified TopMark file type identifiers (affects runtime configuration state).
--relative-to Base directory for relative path handling in configuration.
--align-fields Whether to align header fields (captured in configuration).
--header-format Header rendering format override (captured in configuration).
-q, --quiet Suppress TEXT rendering while preserving the command's exit status.

Run topmark config dump -h for the full list of options and help text.

Machine-readable output

Use --output-format json or --output-format ndjson to emit output suitable for tools.

The canonical schema, stable kind values, and shared conventions are documented here:

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.

Machine-readable configuration snapshots emit normalized canonical qualified file type identities after configuration normalization.

Notes:

  • config dump is file-agnostic and emits the effective runtime configuration after applying defaults -> discovered configuratin -> --config files -> CLI overrides, with whole-source TOML validation performed per source before layered configuration merging.
  • With --show-layers, machine-readable output also includes a config_provenance payload before the flattened runtime configuration snapshot.
  • Diagnostics are not emitted for this command; it is an inspection view of the effective runtime configuration.

JSON schema

A single machine-readable JSON document is emitted:

{
  "meta": { /* MetaPayload */ },
  "config": { /* ConfigPayload (effective runtime snapshot) */ }
}

With --show-layers, the JSON envelope becomes:

{
  "meta": { /* MetaPayload */ },
  "config_provenance": { /* TomlProvenancePayload */ },
  "config": { /* ConfigPayload */ }
}

NDJSON schema

NDJSON is a stream where each line is a machine-readable JSON record.

Default mode:

  1. kind="config" (effective runtime configuration snapshot)

Example:

{"kind":"config","meta":{...},"config":{...}}

With --show-layers:

  1. kind="config_provenance" (layered provenance export snapshot)
  2. kind="config" (effective runtime configuration snapshot)

Example:

{"kind":"config_provenance","meta":{...},"config_provenance":{...}}
{"kind":"config","meta":{...},"config":{...}}

Exit codes

topmark config dump is an informational inspection command and exits with SUCCESS (0) when the effective runtime configuration is rendered successfully.

Common config dump exit codes:

Scenario Exit code
Effective runtime configuration rendered successfully SUCCESS (0)
Invalid CLI usage USAGE_ERROR (64)
Configuration cannot be loaded for command CONFIG_ERROR (78)

Notes:

  • This command does not process files and does not use file-processing exit codes such as WOULD_CHANGE (2), FILE_NOT_FOUND (66), or IO_ERROR (74).
  • Invalid positional paths are reported as CLI usage errors, not file-processing diagnostics.
  • --quiet is supported for TEXT rendering and suppresses the rendered TOML while preserving the exit status.
  • Markdown and machine-readable JSON/NDJSON output ignore TEXT-oriented quiet and verbosity controls.

See Exit codes for the complete CLI-wide exit-code contract.

Shared output controls

config dump prints configuration; it does not render program output with per-file diagnostics.

  • In TEXT rendering, -v adds BEGIN/END markers around the TOML output.
  • --quiet suppresses TEXT rendering while preserving the exit status.
  • Markdown output is document-oriented and ignores TEXT-oriented verbosity and quiet controls.
  • Machine-readable JSON and NDJSON output ignore TEXT-oriented verbosity and quiet controls.

Notes

  • The output reflects the effective runtime configuration TopMark would use if you ran file-processing commands (check, strip, or probe) with the same configuration-related flags in the current working directory, after TOML-layer validation and layered configuration merging.
  • For per-file configuration (e.g., overrides that may depend on path), consider a future option like --for FILE (not currently implemented), similar to ESLint's --print-config.

Troubleshooting

  • Unexpected file type filter behavior: prefer qualified identifiers such as topmark:python when local identifiers may be ambiguous.
  • Unexpected policy application: inspect normalized identifiers in the dumped runtime configuration.
  • Unexpected configuration layering: use --show-layers to inspect layered provenance and validated TOML fragments.