taplo format: Format TOML Files in CI
taplo format rewrites TOML files to a canonical style, and taplo format --check fails CI if any file is not already formatted.
taplo is a TOML toolkit (formatter, linter, LSP). In CI you usually run taplo format --check to enforce consistent Cargo.toml, pyproject.toml, and config files.
What it does
taplo format (aliased fmt) parses TOML and rewrites it with consistent indentation, key ordering, and alignment. With --check it does not write; it exits non-zero if any file would change, printing which files are unformatted.
Common usage
# format in place
taplo format Cargo.toml
# format every TOML file in the repo
taplo format
# CI gate: fail if anything is not formatted
taplo format --check
# check with a diff of what would change
taplo format --check --diffOptions
| Flag | What it does |
|---|---|
| --check | Do not write; exit 1 if reformatting is needed |
| --diff | Print the diff of proposed changes |
| -o <key=value> | Set a formatter option, e.g. -o align_entries=true |
| --config <file> | Use a specific taplo.toml config |
| --stdin-filepath <path> | Name the input when reading from stdin |
In CI
Run taplo format --check (add --diff so the log shows exactly what is off). Because --check exits 1 on drift, the runner fails the job and the author reformats locally. Commit a taplo.toml so local and CI formatting agree.
Common errors in CI
the file is not correctly formatted (with a non-zero exit) is the expected --check failure; run taplo format to fix it. expected ... found ... or unexpected character is a TOML syntax error, not a format issue; fix the source. command not found: taplo means the binary is not installed; use cargo binstall taplo-cli or the release binary. invalid configuration means a bad taplo.toml.