Skip to content

topmark config init

Purpose: Render the bundled example TopMark TOML template.

The config init subcommand (part of topmark config) prints the bundled example TopMark TOML template. This resource is heavily commented and is intended as a starting point for a new configuration file.

The example includes both layered configuration sections (such as [header], [fields], [formatting], and [files]) and TOML-source-local sections such as [config]. During normal loading, TopMark validates the whole source first and then deserializes only the layered fragment into the effective runtime configuration.

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

# Print a starter configuration to stdout
topmark config init

# Create a new project config file
topmark config init > topmark.toml

# Or integrate into pyproject
topmark config init --pyproject >> pyproject.toml

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

Behavior details

  • [config] - source-local options such as root and strictness behavior
  • [fields] - default header fields (project, license, ...)
  • [header] - order of fields to render in the header
  • [formatting] - layout options (e.g., align_fields)
  • [files] - file discovery knobs (e.g., include_file_types, exclude_file_types)

You can safely edit the generated file to match your project's needs.

Input applicability

config init renders a bundled example configuration and 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

Use shell redirection (for example, > topmark.toml) to write the generated configuration to a file.

When to use

  • File-agnostic: does not inspect any files. Positional paths are rejected as invalid CLI usage. STDIN content mode (-) and file-list modes (such as --files-from -) do not apply.
  • Non-destructive: writes nothing; you control redirection.
  • Self-documenting: comments explain layered configuration fields, TOML-source-local options, and reasonable defaults.

Output behavior

Output formats:

  • text / markdown: full commented template from the bundled resource. Markdown is document-oriented and ignores TEXT-oriented verbosity controls.
  • json / ndjson: a machine-readable config snapshot produced by parsing and resolving the bundled starter template, without comments or diagnostics.

Notes:

  • Specify --pyproject if you want to add the configuration to your project's pyproject.toml. This nests the example TOML under a [tool.topmark] table.

  • When choosing json or ndjson, TopMark parses and resolves the bundled starter template before emitting the machine-readable snapshot. This preserves template semantics, including TOML-authored runtime sections such as [writer], while omitting comments and formatting.

  • In TEXT rendering, -v adds BEGIN/END markers around the TOML output.

  • Markdown output is document-oriented and ignores TEXT-only verbosity controls.

  • Machine-readable JSON/NDJSON output ignores TEXT-oriented verbosity controls.

Command-specific options

topmark config init supports content-rendering options such as --output-format, --pyproject, --root, color controls, and TEXT verbosity. See topmark config init -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.

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.
  • 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.

Notes:

  • In machine-readable JSON/NDJSON output, config init emits a configuration snapshot produced by parsing and resolving the bundled starter template.
  • The machine-readable output represents the bundled template view, not a discovered or merged project configuration.
  • The snapshot includes TOML-authored runtime sections such as [writer] when they are present in the bundled template, even though those sections are resolved outside the layered configuration model at runtime.
  • Machine-readable configuration snapshots emit normalized canonical qualified file type identities after configuration normalization.
  • No diagnostics are emitted for this command.

JSON schema

A single JSON document is emitted:

{
  "meta": { /* MetaPayload */ },
  "config": { /* ConfigPayload (bundled template snapshot) */ }
}

NDJSON schema

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

Stream:

  1. kind="config" (bundled template snapshot)

Example:

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

Exit codes

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

Common config init exit codes:

Scenario Exit code
Example 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.

  • 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 defaults - show TopMark's canonical built-in default TOML document.

Troubleshooting

  • 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.
  • Need built-in defaults only: use topmark config defaults.