Skip to content

Command-line interface

TopMark provides a deterministic command-line interface supporting:

  • checking header state
  • inserting or updating headers
  • stripping headers
  • inspecting effective runtime configuration
  • generating starter configuration files
  • inspecting registry state and resolution decisions
  • shell tab-completion via Click-generated completion scripts

The CLI is intentionally conservative:

  • commands default to dry-run behavior
  • mutations require --apply
  • unsupported files are skipped diagnostically
  • repeated runs converge to stable results
  • command help and shell completion are available across supported platforms

Note

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

Common workflows

Goal Command More info
Check headers safely in dry-run mode topmark check src/ topmark check, Shared options, Exit codes
Apply header updates explicitly topmark check --apply src/ topmark check, Policies
Remove TopMark headers topmark strip --apply src/ topmark strip, Header placement
Inspect file type resolution topmark probe README.md topmark probe, Filtering
Inspect effective configuration topmark config dump --show-layers topmark config dump, Configuration

Installation

Install TopMark from PyPI:

pip install topmark

Verify the installation:

topmark version

Command structure

The CLI uses the following structure:

topmark COMMAND [COMMAND OPTIONS] [PATHS...]

The root command currently exposes only help (topmark --help). Shared controls such as configuration loading, output format, verbosity, filtering, and mutation flags are exposed only on the command families where they apply.

Examples:

topmark --help

topmark check src/

topmark check --apply src/

topmark strip --apply src/

Command help

Every command and command group provides built-in help output.

Examples:

topmark --help

topmark check --help

topmark config --help

topmark registry filetypes --help

The short form -h is also supported.

Shell tab-completion

TopMark supports shell tab-completion through Click's generated completion scripts.

Shell completion helps with:

  • command discovery
  • subcommand navigation
  • option completion
  • filesystem path completion

Completion support depends on the active shell environment.

Bash (Linux/macOS)

Temporary session setup:

eval "$(_TOPMARK_COMPLETE=bash_source topmark)"

Persistent setup:

echo 'eval "$(_TOPMARK_COMPLETE=bash_source topmark)"' >> ~/.bashrc

Reload the shell configuration:

source ~/.bashrc

Zsh (macOS/Linux)

Temporary session setup:

eval "$(_TOPMARK_COMPLETE=zsh_source topmark)"

Persistent setup:

echo 'eval "$(_TOPMARK_COMPLETE=zsh_source topmark)"' >> ~/.zshrc

Reload the shell configuration:

source ~/.zshrc

Fish (Linux/macOS)

Install the completion script:

_TOPMARK_COMPLETE=fish_source topmark > ~/.config/fish/completions/topmark.fish

Fish automatically loads completion files from this directory.

PowerShell (Windows)

Register completion for the current PowerShell profile:

_TOPMARK_COMPLETE=powershell_source topmark | Out-String | Invoke-Expression

To persist the setup across sessions, add the command to the PowerShell profile referenced by:

$PROFILE

Completion environment variable

Click-based completion uses the _TOPMARK_COMPLETE environment variable.

Supported values include:

  • bash_source
  • zsh_source
  • fish_source
  • powershell_source

For additional Click shell-completion details, see the upstream Click documentation.

Shared options

Common shared options include the following, where supported by the selected command:

Option Description
--config FILE Load and merge an additional configuration file
--apply Apply file mutations instead of dry-run, where supported
-v, --verbose Increase TEXT output detail, where supported
-q, --quiet Suppress TEXT output, where supported
--output-format {text,markdown,json,ndjson} Select output format, where machine-readable output is supported
--color / --no-color Enable or disable colorized terminal output, where supported
--include-file-types Restrict processing to selected file types, where supported
--exclude-file-types Exclude selected file types, where supported

For command applicability, output, verbosity, and formatting options, see Shared options.

Note

CLI spelling vs configuration/API spelling

TopMark uses hyphenated spelling for CLI option names:

topmark check --header-mutation-mode=add-only

For multi-word option values, the CLI accepts both hyphenated and canonical underscore forms:

topmark check --header-mutation-mode=add-only
topmark check --header-mutation-mode=add_only

TOML configuration, Python API values, and machine-readable output use the canonical underscore form:

[policy]
header_mutation_mode = "add_only"

CLI option names themselves do not accept underscores. Use --header-mutation-mode, not --header_mutation_mode.

File type filters

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.

Examples:

topmark check --include-file-types python src/

topmark check --include-file-types topmark:python src/

topmark check --exclude-file-types markdown docs/

File type filters behave consistently across:

  • CLI options
  • TOML configuration
  • API overlays
  • resolution and probe filtering

For canonical file-type identifier semantics and layered configuration behavior, see Configuration.

Command map

Goal Command
Check headers without modifying files topmark check
Apply header insertions or updates topmark check --apply
Remove existing TopMark headers topmark strip
Inspect resolution and processor behavior topmark probe
Validate effective configuration topmark config check
Inspect effective runtime configuration topmark config dump
Generate starter configuration topmark config init
Inspect registry state topmark registry
Display version and environment information topmark version

Main commands

See also:

Command Purpose
topmark check Detect missing, malformed, or outdated headers. Dry-run by default; use --apply to mutate files.
topmark strip Remove existing TopMark headers. Dry-run by default; use --apply to mutate files.
topmark probe Inspect file type resolution, processor binding, filtering, and probe decisions without mutating files.
topmark config Inspect, validate, render, and initialize TopMark configuration.
topmark config check Check the validity of the effective runtime configuration.
topmark config dump Display the effective runtime configuration.
topmark config defaults Display the canonical built-in default TOML representation.
topmark config init Render the bundled starter configuration template.
topmark registry Inspect registered file types, processors, and registry bindings.
topmark registry filetypes Inspect file type identities and their matching rules and policies.
topmark registry processors Inspect header processor identities and their capabilities.
topmark registry bindings Inspect effective bindings between file types and processors.
topmark version Display version and environment information.

Dry-run vs apply

TopMark defaults to dry-run behavior.

Without --apply, commands preview planned changes without mutating files.

Example:

topmark check src/

Apply changes explicitly:

topmark check --apply src/

This safety model helps prevent accidental large-scale repository mutations while preserving preview-oriented workflows.

Diagnostics and exit behavior

The CLI reports:

  • unsupported file types
  • malformed headers
  • skipped files
  • planned mutations
  • write failures
  • configuration validation issues
  • ambiguous or malformed file type identifiers

Diagnostics are designed to remain deterministic and compatible with the stable machine-readable output contracts.