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>, resolved configuration-file path)
  • kind - layer type (e.g. default, discovered)
  • precedence - merge order
  • scope_root - optional applicability root associated with the configuration source
  • toml - the source-local TopMark TOML fragment after TOML-layer validation

The provenance export also records a top-level discovery_anchor, which identifies the resolved filesystem location from which project-chain configuration discovery started. The discovery anchor is distinct from configuration-source origin, layer scope_root, processing targets, and filesystem identity.

For file-backed layers, origin and scope_root describe the resolved configuration-file target used for configuration-source identity. If a configuration file is loaded through a symlink, layered provenance reports the resolved target rather than the symlink spelling.

Configuration-source identity is distinct from processing-target identity. Runtime filesystem-processing commands such as check, strip, and probe evaluate selected processing paths separately, including filesystem-identity normalization and eligibility checks such as hard-link policy. Those runtime checks do not affect configuration loading, layered provenance, applicability evaluation, or runtime configuration serialization.

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

TopMark resolves configuration from defaults, user config, the project chain discovered from the resolved discovery anchor, explicit --config files, and CLI overrides before staged validation produces the effective runtime configuration.

For file-backed configuration sources, TopMark determines configuration-source identity using the resolved configuration-file target. If a configuration file is reached through a symlink, precedence, scope evaluation, applicability checks, and layered provenance operate on the resolved target rather than the symlink spelling. See Configuration discovery, precedence, and policy for the full configuration-loading and validation contract.

This configuration-source identity behavior mirrors only the path-spelling normalization part of TopMark's runtime processing-target identity model. Processing-target eligibility checks such as hard-link policy are evaluated later by runtime filesystem-processing commands and are not part of configuration dumping.

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.

When --config PATH refers to a symlinked configuration file, configuration loading and layered provenance use the resolved configuration target as the configuration source. This mirrors the configuration-source identity model used throughout configuration discovery.

Because config dump does not accept processing paths, project-chain discovery normally starts from the current working directory. If the working directory is reached through a symlink, discovery uses the resolved anchor location when walking the project chain.

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.

Machine-readable configuration provenance uses configuration-source identity based on the resolved configuration-file target. Configuration-source paths reported by machine-readable output therefore describe the resolved configuration target rather than a symlink spelling used to reach it.

Unlike file-processing machine output, configuration machine output does not apply runtime processing-target eligibility checks such as hard-link policy because config dump operates on configuration sources rather than processing targets.

Note

Path representation

TopMark serializes machine-readable filesystem path fields with POSIX / separators on all platforms.

Path serialization is a presentation contract and is distinct from filesystem identity.

TopMark first determines the selected processing path for the filesystem target being processed and then serializes that processing path according to the machine-output contract.

This contract applies to:

  • header metadata path fields;
  • processing machine-output payloads;
  • probe machine-output payloads;
  • configuration machine-output payloads; and
  • TOML/config provenance payloads.

Examples:

real/file.py
./real/file.py
link-to-file.py

may refer to the same filesystem identity and therefore produce the same serialized processing path.

TopMark's machine-readable path fields remain path-based and are derived from the selected processing path for each processing target.

Filesystem identity policy is a separate concern from path serialization. TopMark may apply additional filesystem-identity rules when determining whether a processing target is eligible for processing. For example, selected hard-linked files are detected using device/inode identity and are reported as unsupported processing targets. Such checks do not alter the serialized path values emitted in machine-readable output.

Human-facing output follows display-path policy instead:

  • CLI and Markdown reports may use the host platform's native path representation;
  • STDIN-backed processing displays the logical --stdin-filename when available; and
  • unified diff file labels are human-facing display labels, not machine-readable path fields.

Synthetic configuration-source identifiers (for example built-in defaults) are serialized as stable labels rather than filesystem paths.

Notes:

  • config dump is file-agnostic and emits the effective runtime configuration after applying defaults -> discovered configuration -> --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. The provenance payload includes discovery_anchor, the resolved filesystem location from which project-chain configuration discovery started.
  • File-backed provenance entries use configuration-source identity based on resolved configuration targets. origin and scope_root therefore describe resolved configuration targets rather than symlink spellings.
  • 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 */ }
}

The config_provenance payload reports configuration layers using configuration-source identity and also includes discovery_anchor, the resolved filesystem location from which project-chain configuration discovery started. For file-backed layers, provenance paths describe resolved configuration targets.

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":{...}}

Within config_provenance, discovery_anchor identifies the resolved filesystem location from which project-chain configuration discovery started. It is distinct from configuration-source origin values and layer scope_root values.

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:

  • Click parser-level usage errors (for example, unknown commands, unknown options, or invalid option values) may exit with code 2 before command logic runs.
  • This command does not process files and does not use file-processing exit codes such as WOULD_CHANGE (3), 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.
  • Configuration path differs from invocation spelling: layered provenance and machine-readable provenance report resolved configuration targets. If a configuration file is loaded through a symlink, origin and scope_root may differ from the path spelling supplied on the command line.
  • Hard-link policy is not reflected in the output: config dump reports configuration state, not processing-target eligibility. Hard-link policy is enforced by runtime filesystem-processing commands such as check, strip, and probe.