Skip to content

cla fmt - format Clarive HCL files

cla fmt: rewrites Clarive HCL files into the canonical style.

Canonical style is what every Clarive tool produces: cla export writes it, the rule editor saves it, and cla fmt restores it after hand editing. Because the style is deterministic, two installs holding the same configuration produce byte-identical files, so git diff only ever shows real changes.

Usage

cla fmt [paths...] [--check] [--stdout] [--recursive] [--indent N]

With no paths, cla fmt formats *.hcl inside ./cla-objects/.

Paths may be files or directories. A directory contributes its *.hcl files; add --recursive to descend into subdirectories.

Note that cla fmt does not scope that default by environment the way cla export and cla import do. After cla -c prod export, the files are in ./cla-objects/prod, where a bare cla fmt will not find them — it reports No HCL files found and exits 2. Use cla fmt --recursive, or name the directory.

cla fmt is also the only one of the HCL commands that rejects an unknown option, with exit 80.

Options

  • --check — do not write anything. Print the files that would change and exit 1 if there are any. Exit 0 when everything is already canonical. Use this in CI to keep a repository formatted.
  • --stdout — print the formatted result instead of writing it. Takes exactly one file.
  • --recursive — descend into subdirectories when a path is a directory.
  • --indent N — write N spaces per nesting level instead of 2, from 1 to 8. Use the same width you gave cla export --indent, or a plain cla fmt puts every file back at 2. Indentation is presentation only: cla import reads a file the same at any width, heredocs included. --check compares against the width you pass.

Exit codes

  • 0 — everything formatted, or already canonical.
  • 1 — --check found files that need formatting.
  • 2 — a file could not be read, written, or parsed.

A file that fails to parse is never rewritten. cla fmt prints the diagnostic with its file:line:column and moves on to the next file.

The canonical style

  • Two spaces per nesting level, unless --indent says otherwise.
  • One space around =, with = aligned inside each run of adjacent attributes. A blank line, a comment or a nested block starts a new run.
  • One blank line between top level blocks. Runs of several blank lines collapse to one.
  • Lists stay on one line while they fit, otherwise one element per line with a trailing comma. Object literals are always expanded.
  • Heredocs keep their delimiter and their content exactly as written. An indented heredoc (<<-EOT) moves with its block: the body sits one level in, the closing delimiter at the block level, and the indentation of each line relative to the others is kept. A plain heredoc (`<