Configuration

complexijs.toml

Settings can live in a complexijs.toml file in the directory where you run the tool. Command line flags always override the file, and the file overrides the defaults.

Full example with every key:

paths = ["src", "lib"]
exclude = ["**/*.test.ts", "vendor/**"]
max-complexity-allowed = 15
quiet = false
failed = false
ignore-complexity = false
color = "auto"        # auto, yes, no
sort = "asc"          # asc, desc, name
check-script = false
no-ignore = false
report-ignored = false
snapshot-create = false
snapshot-ignore = false
output-format = ["json"]
diff = "HEAD"         # git ref to diff against, with ratchet enforcement
# diff-only = "main"  # alternative: same report, no effect on the exit code
staged = false

Precedence

CLI flags > complexijs.toml > built-in defaults.

When the same setting appears in both, the CLI value always wins. For boolean flags, the flag being present on the command line sets the value to true regardless of what the file says.

--plain is CLI-only and is not read from the TOML file.

[tool.complexijs] fallback

If your project already uses a complexijs.toml file for other tools, you can namespace the complexijs settings under a [tool.complexijs] table:

[tool.complexijs]
max-complexity-allowed = 10
exclude = ["vendor/**"]

The format is identical to the top-level form. complexijs tries the top-level parse first; if that fails, it falls back to [tool.complexijs].

Key reference

Key	Type	Default	Notes
paths	string[]	["."]	Paths to analyze
exclude	string[]	[]	Glob patterns to exclude
max-complexity-allowed	integer	15	Threshold for failure
quiet	boolean	false	Suppress per-file console output
failed	boolean	false	Show only functions that fail
ignore-complexity	boolean	false	Do not fail the run on complexity: exit 0 even when functions exceed the threshold
color	string	"auto"	"auto", "yes", or "no"
sort	string	"asc"	"asc", "desc", or "name"
top	integer		Limit output to N results
check-script	boolean	false	Report module-level code as <module>
no-ignore	boolean	false	Disregard all complexijs: ignore / noqa: complexijs markers, analyzing every function
report-ignored	boolean	false	List every ignore marker found
snapshot-create	boolean	false	Write a new snapshot file
snapshot-ignore	boolean	false	Ignore the snapshot and enforce raw threshold
output	string		Directory or prefix for report files
output-format	string[]	[]	"csv", "json", and/or "sarif"
diff	string		Git ref to diff against; regressions over the threshold fail the run
diff-only	string		Git ref to diff against for reporting only. Mutually exclusive with diff; setting both warns and keeps diff-only. Passing either flag on the command line ignores both file values.
staged	boolean	false	Diff the git index instead of the working tree