topmark config defaults

Purpose: Show the built-in default TopMark TOML document.

The config defaults subcommand (part of topmark config) prints TopMark's canonical built-in default TOML representation. It uses a cleaned, comment-free TOML document generated from the built-in defaults table (no project files are discovered or merged).

Because the output is generated from TopMark's built-in defaults, it reflects only the built-in default TOML surface. Source-local TOML sections such as [config] and runtime-facing sections such as [writer] are included when they are part of the canonical defaults, but no project, user, or explicitly supplied config files are discovered or merged.

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

# Show the built-in default configuration (TOML)
topmark config defaults

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

---

Behavior details

• Isolated: ignores project/user configuration files and CLI overrides.
• File-agnostic: does not resolve or process any PATHS. Positional paths are rejected as invalid CLI usage. STDIN content mode (-) and file-list modes (such as --files-from -) do not apply.
• Reference: useful for understanding the canonical built-in defaults, header layout, runtime policy behavior, and TOML/configuration/runtime separation.

How configuration is resolved

TopMark merges configuration from defaults -> user -> project chain -> --config -> CLI. Globs are evaluated relative to the workspace base (relative_to). Paths to other files (like exclude_from) are resolved relative to the config file that declared them.

See: Configuration discovery, precedence, and policy.

---

When to use

• To compare your project's configuration with the baseline shipped by TopMark.
• To seed your own configuration manually (you can copy and modify the parts you need).
• To debug why a field or policy is present when you did not set it explicitly.

---

Input applicability

config defaults is a pure informational command that emits built-in defaults only. It does not accept file-processing inputs:

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

This ensures the output always reflects only the built-in defaults, independent of any workspace state.

No configuration discovery, project traversal, runtime resolution and filtering, or runtime policy overlay evaluation occurs for this command.

---

Command-specific options

This command is intentionally minimal and usually has no options. See topmark config defaults -h for any environment-specific flags that may be available in your build.

topmark config defaults supports content-rendering options such as --output-format, --pyproject, --root, color controls, and TEXT verbosity. See topmark config defaults -h for the complete command help.

Note: -v / --verbose applies only to TEXT rendering. This pure content-producing command does not support --quiet. Markdown and machine-readable formats ignore TEXT-oriented verbosity controls.

---

Output behavior

Output formats:

• text / markdown: minimal, comment-free TOML. Markdown is document-oriented and ignores TEXT-oriented verbosity controls.
• json / ndjson: a machine-readable config snapshot derived from the canonical built-in defaults table, including TOML-authored runtime sections such as [writer] when present. No diagnostics are emitted. Machine-readable formats ignore TEXT-oriented verbosity controls.

---

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:

• Machine-readable output
• Machine-readable format conventions

Note

• Verbosity (-v / --verbose) affects only TEXT rendering.
• This command does not support -q / --quiet because it is a pure informational, content-producing command without a meaningful status or mutation signal.
• 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 defaults is file-agnostic and emits a configuration snapshot derived only from the canonical built-in defaults table (no discovery and no merge with project/user config).
• The machine-readable snapshot includes TOML-authored runtime sections such as [writer] when they are present in the canonical defaults, even though those sections are resolved outside the layered configuration model at runtime.
• No diagnostics are emitted for this command.

JSON schema

A single JSON document is emitted:

{
  "meta": { /* MetaPayload */ },
  "config": { /* ConfigPayload (canonical defaults snapshot) */ }
}

NDJSON schema

NDJSON is a stream where each line is a JSON object. Every record includes kind and meta.

Stream:

1. kind="config" (canonical defaults snapshot)

Example:

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

---

Exit codes

topmark config defaults is a pure informational/content-producing command and exits with SUCCESS (0) on successful execution.

Common config defaults exit codes:

Scenario	Exit code
Defaults rendered successfully	SUCCESS (0)
Invalid CLI usage	USAGE_ERROR (64)

Notes:

• This command does not inspect project 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 unsupported because the command's primary purpose is to emit content.

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

---

Related commands

• topmark config check - validate the effective runtime configuration and staged configuration-loading diagnostics.
• topmark config dump - show the effective runtime configuration, including normalized canonical file type identities.
• topmark config init - print the bundled example TopMark TOML template.

---

Related docs

• Command overview
• Configuration
• Filtering
• Policies
• Configuration discovery, precedence, and policy
• Configuration schema
• Machine-readable output
• Machine-readable format conventions
• Exit codes
• Terminology and Canonical Vocabulary

---

Troubleshooting

• Unexpected defaults: remember that config defaults ignores all project, user, and CLI overlay configuration.
• Unexpected identifier formatting: machine-readable output may emit normalized canonical qualified identifiers such as topmark:python.
• Need the real effective runtime configuration: use topmark config dump instead.