cue fmt: Format CUE Files in CI
cue fmt rewrites CUE source into canonical formatting, in place by default.
cue fmt keeps CUE diffs clean. Unlike some formatters it rewrites in place, so a CI gate compares against a clean git tree rather than using a dedicated check flag.
What it does
cue fmt parses the given CUE files or packages and rewrites them in canonical form. It edits files in place. To gate CI, run it and then check that git reports no changes, since cue fmt does not have a standalone diff/check exit mode.
Common usage
# format files/packages in place
cue fmt ./...
# CI gate: format, then fail if anything changed
cue fmt ./...
git diff --exit-codeOptions
| Form | What it does |
|---|---|
| cue fmt <files|pkg> | Format the named files or package in place |
| cue fmt ./... | Recursively format all packages under the current dir |
| git diff --exit-code | The idiomatic CI gate after running cue fmt |
In CI
Because cue fmt writes in place, the standard gate is to run it on a clean checkout and then git diff --exit-code; a non-zero exit means someone committed unformatted CUE. Pin the cue version so formatting is stable across runner images.
Common errors in CI
If git diff --exit-code fails after cue fmt, the committed files were not formatted; run cue fmt locally and commit. A parse failure prints "expected ... found ..." with a file position, meaning the source does not parse and cannot be formatted; fix the syntax first. Formatting a package with build errors can also surface "cannot find package".