caddy fmt: Format and Lint a Caddyfile
caddy fmt rewrites a Caddyfile into the canonical format, and with --diff it shows what would change without touching the file.
caddy fmt keeps Caddyfiles consistent and surfaces obvious structural mistakes. Use --diff in CI to fail when a committed Caddyfile is not formatted.
What it does
caddy fmt reads a Caddyfile and outputs the canonically formatted version to stdout. --overwrite writes the formatted result back to the file, and --diff prints a unified diff of the changes it would make. It is a formatter, not a full validator, so it does not adapt or provision modules the way caddy validate does.
Common usage
# print the formatted Caddyfile
caddy fmt Caddyfile
# rewrite the file in place
caddy fmt --overwrite Caddyfile
# CI gate: fail if not already formatted
caddy fmt --diff CaddyfileOptions
| Flag | What it does |
|---|---|
| <file> | Caddyfile to format (default ./Caddyfile) |
| --overwrite | Write the formatted result back to the file |
| --diff | Print a diff of the changes instead of the result |
In CI
Run caddy fmt --diff Caddyfile and fail the job if it prints any diff, mirroring how gofmt or prettier gates work. Note fmt only checks formatting; keep caddy validate as the separate correctness gate. Some CI setups assert the diff output is empty by checking the exit status combined with output length.
Common errors in CI
A non-empty --diff means the committed Caddyfile is not canonically formatted; run caddy fmt --overwrite and commit. caddy fmt does not catch unknown directives (validate does), so a Caddyfile that passes fmt can still fail caddy validate. "no such file or directory" means a wrong path argument.