CLI reference

Run it with no arguments and it scans the current directory against the default threshold of 15, printing nothing and exiting 0 if everything is under it.

npx bonsai-lint src/

Every flag

Flag	Value	Default	What it does
paths	positional	.	Files or directories to scan.
--over	N|LANG=N	none	Complexity threshold; 15 for everything, or php=15,typescript=20 per language.
--all	none	none	Print every unit, not just those above the threshold.
--format	FORMAT	text	Output format; json is what editors read, github annotates pull requests. One of text, json, github.
--write-baseline	none	none	Record current findings as accepted, so only later regressions fail.
--baseline	PATH	none	Use one baseline file, keyed from the workspace root, instead of each domain's own.
--strict-baseline	none	none	Fail when a baseline entry is looser than the code.
--lang	ID	none	Restrict the scan to these languages (php, typescript, vue, go, java, python).
--domain	NAME	none	Restrict the scan to one named domain.
--config	PATH	none	Start config discovery here instead of the first scanned path.
--allow-no-files	none	none	Succeed instead of failing when no supported file is found.
--no-toplevel	none	none	Do not score code outside any function.
--stdin	none	none	Read one file's contents from stdin, so unsaved editor buffers can be analysed.
--stdin-path	PATH	none	The path the stdin contents should be attributed to.
--jobs, -j	N	0	How many files to score at once; 0 asks the machine.

Worked examples

bonsai-lint --domain web                       # one declared domain only
bonsai-lint --baseline PATH .                  # one baseline file for the whole repo, wherever you choose
bonsai-lint --strict-baseline .                # fail while the baseline accepts more than the code needs
bonsai-lint --format github .                  # annotate the pull request from GitHub Actions
bonsai-lint --config packages/web src/         # discover config from here, not from the first path
bonsai-lint --no-toplevel src/                 # skip code outside any function
bonsai-lint --stdin --stdin-path src/a.php < buffer   # score an unsaved buffer as that file
bonsai-lint --jobs 4 .                         # cap the workers; 0 or absent uses every core
bonsai-lint --allow-no-files a.d.ts gen.go     # pass when none of the paths can be scored

Exit codes

Code	Meaning
0	Nothing over the threshold. A clean run prints nothing.
1	Something is over the threshold, a strict baseline accepts more than the code needs, or the scan could not be trusted: an unreadable path, or no supported files found.
2	Usage error, from the argument parser.

The second row is the one worth internalising. A gate that cannot read what it was pointed at must not report success, so an unreadable file fails the run rather than quietly shrinking the set of things checked.