Skip to content

topmark config

TopMark exposes a config command group to inspect and scaffold configuration.

Note

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

Subcommands

Command Purpose
topmark config check Validate the effective runtime configuration and report diagnostics.
topmark config dump Display the effective runtime configuration and layered provenance information.
topmark config defaults Show the built-in default TopMark TOML document.
topmark config init Render the bundled starter TopMark TOML configuration template.

Source-local options under [config] / [tool.topmark.config] (such as root and strict) are resolved during configuration loading. They do not participate in layered configuration merging, but influence discovery and validation behavior.

Note

[config].strict is a TOML-source-local strictness preference controlling staged configuration-loading validation for the current TOML source.

Effective strictness is evaluated across:

  • TOML-source diagnostics;
  • merged-config diagnostics;
  • runtime applicability diagnostics.

When strict validation fails, TopMark exits with CONFIG_ERROR. The diagnostics that triggered the failure remain visible in human-readable and machine-readable output formats.

strict is resolved during TOML loading and does not become a layered configuration field.

For the full discovery, precedence, path-resolution, and staged validation contract, see Configuration discovery, precedence, and policy.

Configuration and policy values handled by these commands are part of the stable public configuration surface. Internal helper types such as PolicyOverrides and ConfigOverrides are not exposed here; they are used internally by CLI/API orchestration. When using the Python API, provide plain mapping-based inputs via config=..., policy=..., and policy_by_type=....

API overlays follow the same identifier normalization and runtime policy-resolution semantics as TOML configuration and CLI filtering. These semantics are configuration concerns and are distinct from runtime filesystem-identity evaluation for selected processing paths.

TopMark performs whole-source TOML validation during loading before layered configuration merging and runtime applicability evaluation. Unknown sections or keys, malformed section shapes, and missing known sections are reported as configuration diagnostics before staged configuration-loading validation semantics are applied. Only validated layered configuration fragments are passed to the configuration layer for merging.

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.

Input applicability

The config command family is file-agnostic. These commands operate on configuration state and do not process source files.

Configuration-source identity is resolved during configuration loading. Configuration discovery starts from a discovery anchor (typically the current working directory for config commands). Project-chain discovery walks upward from the resolved discovery anchor before configuration-source identity is established for discovered configuration files.

Runtime processing-target identity, including filesystem-identity normalization and hard-link eligibility checks, is evaluated later by filesystem-processing commands such as check, strip, and probe.

Across all config subcommands:

  • positional PATH arguments are rejected as invalid CLI usage
  • - is not a content-STDIN sentinel
  • --stdin-filename does not apply
  • file-list STDIN modes (for example, --files-from -) do not apply

Config discovery applies only where explicitly documented (config check, config dump) and is not used by purely informational commands (config defaults, config init).

Shared configuration semantics

The config command family reflects the same stable configuration contract used by:

  • CLI processing commands
  • API overlays
  • runtime resolution and filtering
  • machine-readable output
  • runtime policy lookup

Configuration handling intentionally does not support:

  • fuzzy matching for file type identifiers
  • implicit namespace fallback
  • automatic alias expansion
  • silent ambiguity resolution

Shared behavior

Exit codes

Exit-code behavior for config subcommands follows a consistent pattern:

  • Informational commands (config dump, config defaults, config init) exit with SUCCESS (0) on success.
  • Validation command (config check) exits with:
  • SUCCESS (0) when configuration validation succeeds.
  • CONFIG_ERROR (78) when configuration validation fails.
  • CLI usage errors (invalid options, incompatible flags) exit with USAGE_ERROR (64) when handled by TopMark command logic.
  • Configuration loading and validation failures use CONFIG_ERROR (78) where applicable.
  • Unexpected internal failures exit with UNEXPECTED_ERROR (255).

Notes:

  • CONFIG_ERROR (78) covers both configuration-loading failures and completed validation runs that report configuration errors.
  • Click parser-level usage errors (for example, unknown commands, unknown options, or invalid option values) may exit with code 2 before command logic runs.

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

Output behavior

Note on output controls:

  • -v / --verbose applies only to TEXT rendering across all config subcommands.
  • --quiet is supported only for commands that provide a meaningful status or inspection signal (config check, config dump). Pure content-producing commands (config defaults, config init) do not support --quiet.

When using topmark config dump --show-layers, the command also exposes layered configuration provenance in addition to the flattened effective runtime configuration. This layered provenance view reflects how configuration was built from individual TOML sources (defaults, discovered config, CLI overrides) and includes source-local TOML fragments. This includes the original TOML fragments (after schema validation) that contributed to each layer.

Machine-readable configuration snapshots emit normalized canonical qualified file type identities after configuration normalization. They do not apply runtime processing-target eligibility checks such as hard-link policy because the config command family operates on configuration state rather than source-file processing targets.

Strictness and provenance

When running config check, effective validation strictness is determined by:

  1. CLI override (--strict / --no-strict)
  2. TOML value (strict)
  3. default non-strict behavior

Warnings are treated as errors only when strict config checking is enabled. Identifier ambiguity, malformed identifiers, and runtime applicability diagnostics participate in this staged validation flow. For the stable 1.x line, this evaluation occurs over staged configuration-loading validation, while only the flattened compatibility diagnostics surface is exposed at CLI, API, and machine-readable output boundaries.

Note that strict is a source-local TOML option, not a layered configuration field. It influences validation behavior but is not part of the final merged configuration; however, it is visible in layered provenance output (config dump --show-layers).

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 using topmark config dump, or inspect file type resolution using topmark probe.
  • Unexpected validation failures: use topmark config check together with -vv or machine-readable output to inspect staged validation diagnostics.