CLI Reference

The complete reference for everything cmakefmt can do from the command line. If you just want to get up and running, start with Install first and come back here when you want the full picture.

Synopsis

cmakefmt [OPTIONS] [FILES]...

The Four Main Ways To Run `cmakefmt`

Pattern	What it does
`cmakefmt CMakeLists.txt`	Format one file to stdout.
`cmakefmt dir/`	Recursively discover CMake files under that directory.
`cmakefmt`	Recursively discover CMake files under the current working directory.
`cmakefmt -`	Read one file from stdin and write formatted output to stdout.

How Input Selection Works

One rule governs everything:

direct file arguments always win

If you pass a file path explicitly, cmakefmt processes it even if an ignore file or regex would have excluded it during discovery.

Ignore rules only affect:

directory discovery
--files-from
--staged
--changed

Input Selection Flags

Flag	Meaning
`--files-from <PATH>`	Read more input paths from a file, or `-` for stdin. Accepts newline-delimited or NUL-delimited path lists.
`--path-regex <REGEX>`	Filter discovered CMake paths. Direct file arguments are not filtered out.
`--ignore-path <PATH>`	Add extra ignore files during recursive discovery. Direct file arguments still win.
`--no-gitignore`	Stop honoring `.gitignore` during recursive discovery.
`--staged`	Use staged Git-tracked files instead of explicit input paths.
`--changed`	Use modified Git-tracked files instead of explicit input paths.
`--since <REF>`	Choose the Git base ref used by `--changed`. Without it, `HEAD` is the base.
`--stdin-path <PATH>`	Give stdin formatting a virtual on-disk path for config discovery and diagnostics.
`--lines <START:END>`	Restrict formatting to one or more inclusive 1-based line ranges on a single target.

Output Mode Flags

Flag	Meaning
`-i`, `--in-place`	Rewrite files on disk instead of printing formatted output.
`--check`	Exit with code `1` when any selected file would change.
`--list-changed-files`	Print only the files that would change after formatting.
`--list-input-files`	Print the selected input files after discovery and filtering, without formatting them.
`--diff`	Print a unified diff instead of the full formatted output.
`--report-format <human\|json\|github\|checkstyle\|junit\|sarif>`	Switch between human output and CI/editor-friendly machine reporters.
`--colour <auto\|always\|never>`	Highlight changed formatted output lines in cyan. `auto` only colors terminal output.

Execution Flags

Flag	Meaning
`--debug`	Emit discovery, config, barrier, and formatter diagnostics to stderr.
`--quiet`	Suppress per-file human output and keep only summaries plus actual errors.
`--keep-going`	Continue processing later files after a file-level parse/format error.
`--required-version <VERSION>`	Refuse to run unless the current `cmakefmt` version matches exactly. Useful for pinned CI and editor wrappers.
`--verify`	Parse the original and formatted output and reject the result if the CMake semantics change.
`--fast`	Skip semantic verification, including the default rewrite-time verification used by `--in-place`.
`--cache`	Cache formatted file results for repeated runs on the same files.
`--cache-location <PATH>`	Override the cache directory. Supplying it also enables caching.
`--cache-strategy <metadata\|content>`	Choose whether cache invalidation tracks file metadata or file contents.
`--require-pragma`	Format only files that opt in with a `# cmakefmt: enable` style pragma.
`-j`, `--parallel [JOBS]`	Enable parallel file processing when explicitly requested. If no value is given, use the available CPU count.
`--progress-bar`	Show a progress bar on stderr during `--in-place` multi-file runs.

Config And Conversion Flags

Flag	Meaning
`--dump-config [FORMAT]`	Print a starter config template and exit. Defaults to YAML; pass `toml` for TOML.
`--generate-completion <SHELL>`	Print shell completions for packaging or local shell setup.
`--generate-man-page`	Print a roff man page for packagers and Unix-like installs.
`--show-config [FORMAT]`	Print the effective config for a single target and exit. Defaults to YAML; pass `toml` for TOML.
`--show-config-path`	Print the selected config file path for a single target and exit. `--find-config-path` is an alias.
`--explain-config`	Explain config resolution for a single target, or for the current working directory when no explicit file is given.
`--convert-legacy-config <PATH>`	Convert a legacy `cmake-format` JSON/YAML/Python config file to `.cmakefmt.toml` on stdout.

Config Override Flags

Flag	Meaning
`-c`, `--config-file <PATH>`	Use one or more specific config files instead of config discovery. Later files override earlier ones. `--config` remains a compatibility alias.
`--no-config`	Ignore discovered config files and explicit `--config-file` entries. Only built-in defaults plus CLI overrides remain.
`-l`, `--line-width <N>`	Override `format.line_width`.
`--tab-size <N>`	Override `format.tab_size`.
`--command-case <lower\|upper\|unchanged>`	Override `style.command_case`.
`--keyword-case <lower\|upper\|unchanged>`	Override `style.keyword_case`.
`--dangle-parens <true\|false>`	Override `format.dangle_parens`.

Exit Codes

0: success
1: --check or --list-changed-files found files that would change
2: parse, config, regex, or I/O error

Common Examples

Format One File To Stdout

cmakefmt CMakeLists.txt

Prints the formatted file to stdout. The file on disk is untouched.

Rewrite Files In Place

cmakefmt --in-place .

The “apply formatting now” mode. Every discovered CMake file gets rewritten. In-place rewrites also verify parse-tree stability by default; use --fast only when you are intentionally trading that extra safety check for throughput.

Verify A Dry Run Semantically

cmakefmt --verify CMakeLists.txt

This keeps stdout output, but also reparses both the original and formatted source and rejects the result if the parsed CMake structure changes.

Use `--check` In CI

cmakefmt --check .

Typical human-mode output:

would reformat src/foo/CMakeLists.txt
would reformat cmake/Toolchain.cmake

summary: selected=12 changed=2 unchanged=10 failed=0

Exit code 0 means nothing would change. Exit code 1 means at least one file is out of format — exactly what CI needs.

If your CI system prefers structured annotations or standard interchange formats, switch reporters:

cmakefmt --check --report-format json .
cmakefmt --check --report-format github .
cmakefmt --check --report-format checkstyle .
cmakefmt --check --report-format junit .
cmakefmt --check --report-format sarif .

Pin The Formatter Version In Automation

cmakefmt --required-version 0.0.1 --check .

This makes shell scripts and editor wrappers fail fast when the installed binary is not the exact version the workflow expects.

List Only The Files That Would Change

cmakefmt --list-changed-files --path-regex 'cmake|toolchain' .

Typical output:

cmake/Toolchain.cmake
cmake/Warnings.cmake

Useful for editor integration, scripts, and review tooling that needs a precise list without actually reformatting anything.

List The Selected Input Files Without Formatting Them

cmakefmt --list-input-files --path-regex 'cmake|toolchain' .

Typical output:

cmake/Toolchain.cmake
cmake/Warnings.cmake
cmake/modules/CompilerOptions.cmake

This is the pure discovery mode. It walks the file tree, applies ignore files and filters, then prints the selected CMake inputs without parsing or formatting them.

Show The Actual Patch

cmakefmt --diff CMakeLists.txt

Typical output:

--- CMakeLists.txt
+++ CMakeLists.txt.formatted
@@
-target_link_libraries(foo PUBLIC bar baz)
+target_link_libraries(
+  foo
+  PUBLIC
+    bar
+    baz)

Quiet CI Output

cmakefmt --check --quiet .

Typical effect:

summary: selected=48 changed=3 unchanged=45 failed=0

A clean log with a reliable exit code — ideal for high-volume CI pipelines.

Cache Repeated Runs

cmakefmt --cache --check .
cmakefmt --cache-location .cache/cmakefmt --cache-strategy content --check .

Use metadata-based invalidation for speed or content-based invalidation when you want the cache to ignore timestamp-only churn.

Roll Out Formatting Gradually

cmakefmt --require-pragma --check .

Then opt individual files in with a short marker:

# cmakefmt: enable

cmakefmt also accepts # fmt: enable and # cmake-format: enable as equivalent opt-in pragmas.

Continue Past Bad Files

cmakefmt --check --keep-going .

Typical effect:

error: failed to parse cmake/generated.cmake:...
error: failed to read vendor/missing.cmake:...

summary: selected=48 changed=3 unchanged=43 failed=2

Without --keep-going, the run stops at the first file-level error.

Format Only Staged Files

cmakefmt --staged --check

The easiest pre-commit or pre-push workflow — only touches files that are already part of the current Git change.

Format Only Changed Files Since A Ref

cmakefmt --changed --since origin/main --check

Perfect for PR workflows. Checks only “what this branch changed” rather than the entire repository.

Feed Paths From Another Tool

git diff --name-only --diff-filter=ACMR origin/main...HEAD | \
  cmakefmt --files-from - --check

--files-from accepts newline-delimited or NUL-delimited path lists, so it composites cleanly with any tool that can emit file paths.

Stdin With Correct Config Discovery

cat src/CMakeLists.txt | cmakefmt - --stdin-path src/CMakeLists.txt

Without --stdin-path, stdin formatting has no on-disk context for config discovery or path-sensitive diagnostics.

Partial Formatting For Editor Workflows

cmakefmt --stdin-path src/CMakeLists.txt --lines 10:25 -

Use this when an editor wants to format only a selected line range instead of rewriting the whole buffer.

See Which Config Was Selected

cmakefmt --show-config-path src/CMakeLists.txt

Typical output:

/path/to/project/.cmakefmt.yaml

Inspect The Effective Config

cmakefmt --show-config src/CMakeLists.txt
cmakefmt --show-config=toml src/CMakeLists.txt

Prints the fully resolved config after discovery plus any CLI overrides. No more guessing what the formatter is actually using.

Explain Config Resolution

cmakefmt --explain-config

Typical output includes:

the target path being resolved
config files considered
config file selected
CLI overrides applied

Generate A Starter Config

cmakefmt --dump-config > .cmakefmt.yaml
cmakefmt --dump-config toml > .cmakefmt.toml

YAML is the default because it is easier to maintain once you start defining larger custom command specs.

Convert An Old `cmake-format` Config

cmakefmt --convert-legacy-config .cmake-format.py > .cmakefmt.toml

The fastest path through a legacy config migration.

Discovery Precedence And Filtering Rules

Direct file arguments are always processed, even if an ignore rule would skip them.
Recursive discovery honors .cmakefmtignore and, by default, .gitignore.
--ignore-path adds more ignore files for discovered directories only.
--files-from, --staged, and --changed still pass through normal discovery filters when they produce directories or paths that need filtering.
--show-config-path, --show-config, and --explain-config resolve a single target context and make the selected config path(s) visible.
--no-config disables config discovery entirely.

Diagnostic Quality

For parse and config failures, cmakefmt prints:

the file path
line and column information
source context
likely-cause hints when possible
a repro hint using --debug --check

When formatting results surprise you rather than hard-failing, reach for --debug first.

Keyboard shortcuts

cmakefmt: Fast CMake Formatting