Command-line interface¶

Konform: A fast and extendable multi-rule Python linter.

konform [OPTIONS] [COMMAND]

Command	Description
`check`	Lint Python files for rule violations (default when no subcommand given)
`server`	Start the Language Server (communicates over stdin/stdout)
`rule`	List or explain rules
`ast`	Print the syntax tree as KST rules see it (kinds, names, resolved qualified names). Use it to write `match` conditions
`version`	Print konform's version
`clean`	Clear any caches in the current directory or directories
`init`	Initialise konform in the current directory
`completions`	Print a shell completion script to stdout. Example: `konform completions zsh > ~/.zfunc/_konform`

Global options¶

Available on every command.

General¶

Option	Description
`--color <COLOR>`	Control when coloured output is used • `auto`: Emit colours when stderr is a TTY and NO_COLOR is unset (default) • `always`: Always emit ANSI colours • `never`: Never emit ANSI colours Default: `auto` Environment variable: `KONFORM_COLOR`
`--isolated`	Ignore all configuration files; use built-in defaults

Log levels¶

Option	Description
`-v, --verbose`	Enable verbose logging
`-q, --quiet`	Print violations only; suppress hints, summary, and progress output
`-s, --silent`	Suppress all output. Exits 1 on violations, 0 otherwise

check¶

Lint Python files for rule violations (default when no subcommand given)

konform check [OPTIONS] <FILE_PATHS>...

Arguments¶

Argument	Description
`<FILE_PATHS>...`	Files or directories to process. Use '.' for the current directory

Rule selection¶

Option	Description
`--select <SELECT>`	Enable only these rule codes or category prefixes (comma-separated). Overrides the `select` list in `[tool.konform.lint]`. Example: `--select KIS` enables all KIS* rules.
`--ignore <IGNORE>`	Disable these rule codes or category prefixes (comma-separated). Merged with the `ignore` list in `[tool.konform.lint]`.
`--extend-select <EXTEND_SELECT>`	Like `--select`, but adds codes on top of those already configured. Unlike `--select`, this does not override the configured list. Example: `--extend-select KPT` also runs all KPT* rules.
`--extend-ignore <EXTEND_IGNORE>`	Like `--ignore`, but adds codes on top of those already configured

File selection¶

Option	Description
`--exclude <EXCLUDE>`	Exclude files matching these glob patterns. Comma-separated. Replaces the `exclude` list in `[tool.konform]`. Example: `--exclude "tests/,/migrations/**"`
`--extend-exclude <EXTEND_EXCLUDE>`	Like `--exclude`, but adds patterns on top of those already configured
`--per-file-ignores <PER_FILE_IGNORES>`	Suppress specific rules for files matching a glob pattern. Format: `GLOB:CODE[,CODE,...]`. The glob is matched against the file path relative to the project root. Codes support the same prefix matching as `--ignore`. Overrides the `per-file-ignores` table from the config file. Example: `--per-file-ignores "tests/**:KIS001,KPT"`
`--extend-per-file-ignores <EXTEND_PER_FILE_IGNORES>`	Like `--per-file-ignores`, but merges with the configured list instead of replacing it

Options¶

Option	Description
`--config <CONFIG>`	Path to a custom config file (`pyproject.toml` or `konform.toml`)
`--stdin-filename <STDIN_FILENAME>`	Filename to use when reading from stdin (`-`). Sets the displayed path for violations and is used for config-path matching (e.g. `--exclude` glob patterns). Ignored when `-` is not in FILE_PATHS.
`--fix`	Apply auto-fixes in-place, then report any remaining violations
`--unsafe-fixes`	Also apply fixes marked unsafe (may not preserve exact behavior). Ruff-style separation: some rules' fixes can't fully rule out changing program behavior in edge cases (e.g. KIS002), so they're excluded from plain `--fix` unless this flag is also passed.
`--diff`	Print a unified diff of what `check --fix` would change to stdout. Exits 1 if any file would be modified, 0 if all files are already clean.
`--show-files`	Print the list of files konform would check, then exit 0
`--show-settings`	Print the settings in effect (config file, `extend` chain, CLI overrides applied, enabled rules) as TOML, then exit 0
`--output-format <OUTPUT_FORMAT>`	Output serialisation format for violations. `json` writes a JSON array to stdout; all other formats write to stderr. • `full`: Ruff-style output with arrows and help lines (default) • `concise`: Concise single-line: `file:line:col: level[RULE] message` (`[*]` marks a fixable violation) • `json`: JSON array written to stdout (machine-readable) • `github`: GitHub Actions workflow command annotations (written to stdout) • `gitlab`: GitLab Code Quality JSON report (written to stdout) • `sarif`: SARIF 2.1.0 JSON (written to stdout) • `junit`: JUnit XML report (written to stdout) • `zuul`: Zuul `zuul_return.yaml` (merged into the file at `--output-path`) Default: `full`
`--statistics`	Show violation counts grouped by rule code after the summary
`--fix-only`	Apply fixes but do not report or exit non-zero for remaining violations. Implies `--fix`.
`--exit-non-zero-on-fix`	Exit with a non-zero status code if any files were modified by `--fix`
`--ignore-noqa`	Ignore all `# noqa` suppression comments; report every violation
`--add-noqa`	Append `# noqa: CODE` to every line that has a violation, then exit 0. Codes are merged into an existing `# noqa: ...` list (sorted, no duplicates); a bare `# noqa` already suppresses everything and is left untouched. When `-` is used as a FILE_PATH, the annotated source is written to stdout instead of back to disk.
`--noqa-reason <TEXT>`	Reason to record with `--add-noqa`, as `# noqa: CODE # TEXT`. Also fills in the reason of existing `# noqa` comments reported by KNQ001 (enable it with `--extend-select KNQ001`).
`-o, --output-file <OUTPUT_FILE>`	Write output to this file instead of stderr. For `--output-format json` the JSON is written here; for other formats the text output is written here instead of stderr.

Miscellaneous¶

Option	Description
`--level <LEVEL>`	Minimum severity level that causes a non-zero exit Default: `error`
`--changed-files-level <CHANGED_FILES_LEVEL>`	Override the exit severity for changed-file violations. Defaults to `--level`
`-n, --no-cache`	Bypass the file-level result cache
`--cache-dir <CACHE_DIR>`	Override the cache directory for this run
`-e, --exit-zero`	Exit with status code 0 even when violations are found. Useful in pre-commit hooks and editor integrations.
`-w, --watch`	Re-run the check whenever a watched `.py` file changes. Watches every path given in FILE_PATHS recursively. Press Ctrl-C to stop. The initial check pass runs immediately before the watch loop starts.
`--output-path <OUTPUT_PATH>`	Path of the Zuul `zuul_return.yaml` written by `--output-format zuul`. Existing content is preserved; only `data.zuul.file_comments` and `data.zuul.warnings` are replaced. Violations in changed files become file comments, all others warnings. Ignored for other output formats. Default: `tmp/zuul/zuul_return.yaml`

server¶

Start the Language Server (communicates over stdin/stdout)

konform server [OPTIONS]

rule¶

List or explain rules

konform rule [OPTIONS]

Options¶

Option	Description
`--list`	List all available rules and exit
`--explain <EXPLAIN>`	Print full documentation for a rule code and exit. Example: `konform rule --explain KIS001`
`--schema`	Print the JSON Schema of the structural rules file and exit. Save it and point your editor at it for completion, e.g. with taplo: `#:schema ./konform-rules.schema.json` at the top of konform_rules.toml.
`--test`	Run the `test.valid` / `test.invalid` snippets embedded in user rules. Exits 1 if any snippet fails, 2 if a rule definition is invalid.

ast¶

Print the syntax tree as KST rules see it (kinds, names, resolved qualified names). Use it to write match conditions

konform ast [OPTIONS] <FILE>

Arguments¶

Argument	Description
`<FILE>`	Python file to print the tree of

version¶

Print konform's version

konform version [OPTIONS]

clean¶

Clear any caches in the current directory or directories

konform clean [OPTIONS]

Options¶

Option	Description
`--config <CONFIG>`	Path to a custom config file (used to discover `cache_dir`)

init¶

Initialise konform in the current directory

konform init [OPTIONS] [PATH]

Arguments¶

Argument	Description
`<PATH>`	Directory to initialise. Defaults to the current working directory Default: `.`

Options¶

Option	Description
`--force`	Overwrite an existing configuration (creates `konform.toml` even when `pyproject.toml` or `konform.toml` already exists)
`--no-patterns`	Skip creating `konform_patterns.toml`
`--diff`	Show what would be created or changed without writing any files

completions¶

Print a shell completion script to stdout.

Example: konform completions zsh > ~/.zfunc/_konform

konform completions [OPTIONS] <SHELL>

Arguments¶

Argument	Description
`<SHELL>`	Shell to generate the completion script for Possible values: `bash`, `elvish`, `fish`, `powershell`, `zsh`