CLI reference
aburi <command> [flags]| Command | Purpose |
|---|---|
init | Detect the project and write aburi.json. |
scan | Analyse the workspace; write the JSON analysis and Markdown. |
diff | Compare two revisions; write the review report. |
explain | Print the detail for one symbol. |
vocab | List the effect ids and extension kinds your plugins declare, and who owns each. |
-v / --version and -h / --help work anywhere and exit 0.
--log-level debug|info|warn|error works on every command too, before it or after it. It sets how much of the run's log (warn: Skipped src/legacy.ts: parse reported a non-recoverable error at 12:4 — …) reaches stderr, from aburi scan and from the scans aburi diff and aburi explain run. The default, warn, shows the warn: lines; info adds a line for each file aburi scan removes, debug a line for every file extracted as well, and error shows none of it. Its lines name no scan; aburi diff writes the base's before the head's. At debug, aburi diff also writes a diff/stage4: line for each Symbol, or pair of Symbols, it would not pair by name, and for each class, namespace or object whose members paired but which it would not pair through them, naming the rule that stopped it. The ⚠ warnings are printed whatever the level. Any other value exits 2. At debug, an error that ends the run with exit 1 or 3 is followed by its stack trace and those of its causes.
On a terminal, stderr is coloured (warnings yellow, errors red, the log dim) and a progress line names the phase of each scan — extracting 412/5002 files — redrawn in place and erased before the results are printed. stdout is never coloured, so piping it gives the same bytes wherever you run. --no-color turns the colour off, before the command or after it, and --ci behaves as the CI variable does (below) for a CI that does not set it.
An option that takes a value takes one. Given twice (--config a.json --config b.json), the command exits 2 and names it rather than keep one and drop the other without a word. --ignore and --fail-on add up instead. A flag, which takes no value, can be repeated, and of a --x / --no-x pair the last one written applies. An option that takes a path exits 2 on an empty one (--config "", --output-dir "") rather than read it as the option left out or as the working directory.
Exit codes
| Code | Meaning |
|---|---|
0 | Success, no gate tripped. |
1 | Runtime failure: an I/O error (a write the disk refused to an output file says which command and which output; one refused on stdout or stderr lets the run finish and clean up, then names the stream on the other: aburi: could not write to stdout: EBADF: bad file descriptor, write; a file or directory the scan may not read is named), an unexpected exception, explain found no match, or vocab who-owns found no owner. |
2 | Bad invocation: an unknown flag, an option that takes one value given twice, an empty path, a missing input file, a malformed --fail-on, an ambiguous explain target, a ref diff cannot resolve, an output path a file already stands on, a config that loads no language plugin. |
3 | Gate. A --fail-on clause tripped, a plugin failed, or the scan read too little of the workspace to be trusted. vocab exits 3 for a plugin that fails to load too. |
CI gates on 3. A reader that stops early does not change the code: aburi diff main..HEAD | head -1 exits 0 or 3 as it would without the pipe.
Environment variables
| Variable | Effect |
|---|---|
ABURI_CONFIG | Config file path. The --config flag wins over it. |
ABURI_LOG_LEVEL | The same as --log-level, which wins over it. A value other than the four levels is ignored. |
CI | CI mode: no progress line, no colour unless FORCE_COLOR is set, and aburi scan behaves as under --no-timestamp. The same as --ci. |
NO_COLOR | Set to anything but blanks, no colour. |
FORCE_COLOR | Empty, 1, true, 2 or 3: colour even when stderr is not a terminal, and in CI mode. Any other value, 0 and false among them, turns it off; the value is read as Node reads it, case and blanks included. It wins over NO_COLOR, and --no-color wins over it. It never brings the progress line, which is drawn only on a terminal outside CI mode. |
Config discovery
--config <path>ABURI_CONFIGaburi.jsonc/aburi.json, walking up from the working directory- Built-in defaults. They load no plugin, so a command that scans exits
2and asks for a language plugin oraburi init.
Paths you give to --config resolve against the working directory. Paths inside the config resolve against the workspace root, which need not be the same directory. aburi scan warns you when the two differ.
aburi diff in ref mode settles which config file to read once, before it checks the base revision out, and scans both revisions with it. The workspace root stays per-scan. See aburi diff below.
aburi init
aburi init [--output <path>] [--force] [--with-suggestions]
[--respect-gitignore | --no-respect-gitignore]Detects the workspace layout, languages, frameworks, and components, and writes a config file.
| Flag | Effect |
|---|---|
--output <path> | Write somewhere other than ./aburi.json. Directories in the path are created if they are missing; a path that cannot hold a file — an existing directory, or a file sitting on its parent path — exits 2 and names it. |
--force | Overwrite an existing file. Without it, an existing file exits 2. |
--with-suggestions | Add comments naming the plugin packages it detected but you have not installed. |
--no-respect-gitignore | Include git-ignored files when taking the language census, and git-ignored project.json files when finding nx projects. A git-ignored directory Aburi may not list then stops init. |
aburi init
aburi init --with-suggestions --output config/aburi.jsoncaburi scan
aburi scan [--output-dir <dir>] [--format json|md|both] [--no-md|--no-json]
[--ignore <glob>]... [--respect-gitignore | --no-respect-gitignore]
[--strict | --no-strict | --discover] [--lsp | --no-lsp]
[--compact] [--quiet] [--no-timestamp] [--concurrency <n>]
[--config <path>]Analyses the workspace and writes aburi.ir.json, workspace.md, and components/*.md. After writing, it removes what an earlier run wrote there that this one does not: the output a --format leaves out, and the page of a component that has since been renamed or removed. aburi.ir.json and workspace.md are recognised by name alone, so a file of yours under either name goes too. A page in components/ is recognised by its name and its first line both: it is Aburi's only when it is named after a component id and its first line is that component's # Component: <id> heading, so your own files there stay. A scan that fails before it has written everything removes nothing. --log-level info prints a line for each file removed.
| Flag | Effect |
|---|---|
--output-dir <dir> | Where to write. Falls back to output.dir in the config, then .aburi. Created if missing; a path a file already stands on exits 2 and names it. A .aburi the run creates directly in the working directory gets a .gitignore that ignores all of it, so git passes over it; a directory that was already there, or one anywhere else, is left as it is. |
--format <fmt> | json, md, or both (default). Without --format, --no-md and --no-json each drop one output. With it, a --no-* that would drop an output --format includes exits 2, and so does dropping both. |
--ignore <glob> | An extra exclusion for this run. Repeatable. |
--respect-gitignore / --no-respect-gitignore | Override the config for this run. |
--strict / --no-strict | Override strict for this run. Strict stops at a value a plugin emits without its manifest declaring it; off, the scan keeps it and records it in aburi-vocab-discovered.json, which a strict scan that completes removes again. |
--discover | The same as --no-strict. With --strict, exits 2. |
--lsp / --no-lsp | Override lsp.enabled for this run. --lsp still needs a server under lsp.servers to talk to. |
--compact | JSON without indentation. |
--quiet | Print the two census lines alone on stdout, not the path of each file written. stderr is unchanged. |
--concurrency <n> | How many worker threads extract the files. By default one fewer than the processors, fewer when free memory or a small workspace calls for it; 1 extracts every file on the main thread. The output is the same at any value. |
--no-timestamp | Omit discoveredAt from aburi-vocab-discovered.json. Implicit when CI is set. aburi.ir.json carries no timestamp either way. |
--config <path> | Use a different config file. |
aburi scan
aburi scan --format json --compact --output-dir dist/aburi
aburi scan --ignore 'src/generated/**'
aburi scan --quietFiles that produce nothing
The scan lists the files it could not use on stderr, grouped by reason, and points at the setting that governs each one. The run still passes. An unparseable file tells you something about your source, not about the scan.
When a scan does exit 3
- Nothing was parsed at all. An
ignorepattern ate the tree, acomponents[].rootsmatched nothing, or no installed plugin claims any extension present. The output is still written. - Coverage fell below
minParsedFileRatio, if you set one. - A plugin could not be loaded. It failed to import, or the registry refused its manifest: a prefix or name another listed plugin already declared, a reserved namespace, a namespace its type may not own. No output is written, and the message names the entry in
aburi.jsonthat loaded it. AframeworkHintsentry the registry refuses exits2instead, naming the entry. - A plugin threw on a file, as opposed to declining it.
- A plugin broke a contract that holds for every file: it returned a Promise from
classify, stamped Symbol ids with no valid language prefix, or refused a value throughctx.registry. The run stops at the first one and no output is written.--discoverdoes not change this: a plugin that refuses a value asked for the refusal itself. - A plugin emitted a value its manifest does not declare, in a strict run (the default). No output is written. Declare the value, or run with
--discoverto keep it and see the full list. - A filename cannot be written down. The analysis has no representation for a path containing a backslash, or for a top-level name that opens with one ASCII letter and a colon (
a:notes.ts,d:data/), which reads as a Windows drive. Filenames differing in Unicode composition alone collapse to one. The scan names each kind on stderr and still analyses the rest. Rename them, or exclude them withignore, doubling the backslash in the glob pattern. - A workspace package sits in such a directory. It cannot be a component, so the scan names it on stderr, even when it holds no source file. Rename the directory.
aburi initnames it too, and still writes the config.
Every command that scans reports the same way. aburi diff runs two scans and labels each one's ⚠ lines: the base by its ref, the head as head (working tree). A pluginOptions key that names no loaded plugin, or the plugin of a frameworkHints entry, is about the config both scans read, so aburi diff says it once, with no label.
aburi diff
aburi diff <base>..<head> [flags]
aburi diff --base <a.json> --head <b.json> [flags]Compares two revisions and writes diff.json and diff.md (and diff.full.md when --max-bytes shortened diff.md).
Ref mode verifies both refs with git, checks out the base into a temporary worktree, and scans it. Aburi scans the head from your working tree, and uses its ref as a label in the report.
Both scans read the head's config — the one discovery finds from your working directory, or the one --config names there. The base revision's own aburi.json is ignored, even when the base ref carries a different one, and a head with no config at all exits 2 without scanning either. Otherwise editing ignore would count as a change to every Symbol the setting covers, and aburi diff HEAD~1..HEAD --fail-on added would fail a pull request that touched no source.
The paths inside that config still resolve per scan: ignore and components[].roots are matched against each revision's own workspace root, so for the base that is the temporary worktree. Plugin refs are the exception. A relative one (./plugins/x.mjs) belongs to the plugin set, which comes from the head along with node_modules, so it is loaded from your working tree for both scans. An absolute one (/opt/plugins/x.mjs) names the same file for both scans, whichever workspace root each has.
File mode compares two aburi.ir.json files you already have. No git, no scanning. Each file records the plugins that made it, and when the two lists differ, aburi diff names each difference in one warning on stderr: a plugin only one side loaded, or one loaded at another version. An effect plugin only the base loaded leaves its effects on the base side alone, so every Symbol that carried one reads as changed. Rescan both with one plugin set, or diff the refs, whose two scans load the head's plugins.
| Flag | Effect |
|---|---|
<base>..<head> | Ref-spec dispatch. A ref git cannot resolve exits 2, and the message says whether that is because the directory is not a repository, the repository has no commits, or the name is unknown. |
--base <path> --head <path> | File-mode dispatch. Mutually exclusive with the ref-spec. |
--fail-on <spec> | The CI gate. Repeatable. See below. |
--fail-on-scope <scope> | all (default) or non-test: whether the gate counts the Symbols of test files. See below. |
--output-dir <dir> | Where to write. Falls back to output.dir, then .aburi, which ignores itself as aburi scan's does when this run creates it directly in the working directory. Created if missing; a path a file already stands on exits 2 and names it. Any diff.json, diff.md or diff.full.md already there is removed before the comparison starts, so a run that fails leaves no earlier report to be mistaken for its own. |
--format <fmt> | json, md, or both. |
--compact | JSON without indentation. |
--filter <statuses> | List only these statuses' changes in diff.md. See below. |
--quiet | Print the glyph line (+5 -3 ~12 ↔2 ⤴1) alone on stdout. stderr, the files written and the exit code are unchanged. |
--max-bytes <n> | Cap diff.md at n bytes. See below. |
--parallel-scans / --no-parallel-scans | Whether the two scans run at once. By default they do on a machine with two or more CPUs, and run in turn on one. The output is the same either way; --no-parallel-scans, one at a time, uses less memory. |
--concurrency <n> | How many worker threads each scan extracts its files on, as for aburi scan. Two scans running at once each have half the free memory, and by default half the processors. |
--config <path> | Use a different config file. |
In ref mode, a scan that did not finish cleanly exits 3 even with no --fail-on. A workspace that aburi scan refuses to call green cannot go green here instead.
aburi diff main..HEAD
aburi diff main..HEAD --fail-on 'removed,dropped-toggled:to-dropped:>10'
aburi diff --base ir-main.json --head ir-branch.json --format md--max-bytes
A GitHub comment body cannot exceed 65536 bytes, and the report is written to be pasted into one. A minimal symbol takes about 210 bytes of it, so a branch adding a few hundred symbols produces a report GitHub refuses outright — the review that needed it most gets nothing.
--max-bytes caps diff.md. It is met least important first, not by cutting the text mid-fence. Sections are kept most important first, each at its smallest — a section of whole symbols as one name-and-location line per symbol — and a section is dropped only when it cannot fit even beside every more important one cut that far. The name lists then get their full entries back, from the top, as far as the budget allows. The report says at the top which sections are short and which went:
> ⚠ **2 sections were omitted** to keep this report within 65507 bytes: 💧 Dropped changes, 🎨 Syntax-only changes. The full report, the same diff without a size cap, is `diff.full.md` beside `diff.md`.The sections that survive are always the important ones: API changes go last, Syntax-only first. diff.json is never capped, so nothing is lost from the artefact you can query. When the cap changed anything, the uncapped report is written beside the capped one as diff.full.md, which is what the note points at. Like diff.json and diff.md, one left from an earlier run is removed before the comparison starts (see --output-dir above).
The CLI has no cap unless you pass one: omitting --max-bytes writes the whole document. --max-bytes 0 is not the way to say that — it exits 2, along with every other value that is not a positive integer.
The GitHub Action passes 65507 for you — 65536 less the hidden marker it prepends — so you only reach for this flag to choose a smaller comment. There, max-bytes: 0 is the spelling for no cap: the action input takes it and passes no flag at all.
aburi diff main..HEAD --max-bytes 65507--filter
--filter narrows diff.md to the changes of the statuses you name, comma-separated: added, removed, changed, moved, moved+changed, dropped-toggled, unknown.
aburi diff main..HEAD --filter added,removedIt narrows that file and nothing else. The Summary line counts every change, and a note under it says how many the filter left out:
> ℹ **Only `added` and `removed` changes are listed.** 12 other Symbol changes are left out of this report; the Summary counts them.A Slice that holds a change you kept is drawn whole, its other members included, so a call path is not cut in two. Component changes, dependency changes and Not compared are listed in full, except a dependency change made by test code whose change the filter left out: it leaves the report with that change, and the note counts it. diff.json keeps every change, and so does the glyph line on stdout.
--fail-on counts every change too, whatever the filter: a display option does not decide whether the build fails. So --filter added --fail-on removed still exits 3 on a removal, and because diff.md does not list the removal, stderr says so ahead of the gate's lines:
⚠ --filter leaves out of diff.md every change that tripped --fail-on removed (1 removed).An empty value, an empty segment (added,) and a word that is no status, removed:duplicate among them, exit 2. Under --format json there is no diff.md to narrow, and --filter warns that it does nothing.
--fail-on grammar
Write comma-separated clauses. Each one may carry a :>N threshold. Without a threshold, one occurrence trips the gate.
--fail-on 'removed,changed:>20,api-changed'Repeating --fail-on adds its clauses after the earlier ones, so --fail-on removed --fail-on 'changed:>20' gates exactly as --fail-on 'removed,changed:>20' does.
| Clause | Matches |
|---|---|
added removed changed moved moved+changed dropped-toggled unknown | Symbols with that status. removed leaves out a removed duplicate. |
removed:duplicate | Removed duplicates: removals whose head revision holds a symbol of the same kind with the same body, as deduplicating two identical helpers into one leaves the other removed. A body with nothing to compare (only calls, or a literal returned) and a symbol a framework plugin classified (a route handler, a React component) are never duplicates. removed,removed:duplicate trips on every removal; a threshold on removed counts only the removals that are not duplicates. |
dropped-toggled:to-dropped dropped-toggled:to-kept | One direction of a boilerplate toggle. |
api-changed logic-changed syntax-changed confidence-changed | Symbols whose change touched that axis. |
Evaluation stops at the first clause that fires, which keeps CI logs short. The line it prints names the Symbols that tripped it, ten at most, one per indented line below it. A removed clause with no removed:duplicate beside it adds a line naming the removed duplicates it did not count, whether it fired or not.
Quote the value
> is a shell redirect. Write --fail-on 'changed:>5', not --fail-on changed:>5.
Unknown tokens, comparators other than >, non-integer thresholds, an empty clause (added,, added,,removed), and an empty value all exit 2, and with --fail-on repeated the message quotes the occurrence at fault. Aburi treats an empty gate as a mistake rather than as "no gate", because it would turn a regression into a green pipeline.
--fail-on-scope
A Symbol of a file your config's testFiles names is test code. diff.md lists its changes in a folded 🧪 Test files section at the end, and --fail-on-scope non-test leaves them out of the gate, so deleting a fixture does not fail the build:
aburi diff main..HEAD --fail-on removed --fail-on-scope non-test--fail-on removed tripped (observed: 1 removed outside test files)
ts:src/billing/legacy.ts#refundInvoiceEvery clause counts that way. A pair is judged by its head: a helper moved out of a test file into src/ counts, one moved into a test file does not. The default, all, counts every change.
aburi explain
aburi explain <target> [--ir <path>] [--output <path>] [--no-rescan] [--debug-resolution]
[--concurrency <n>] [--config <path>]Prints the full detail for one symbol. The target can be:
| Form | Example |
|---|---|
| A full symbol id | ts:src/app/orders/actions.ts#submitOrder |
| A file path | src/app/orders/actions.ts, giving you every symbol in that file |
| A name fragment | submitOrder, matched as a case-sensitive substring |
| Flag | Effect |
|---|---|
--ir <path> | Read an existing analysis instead of scanning. |
--output <path> | Write to a file instead of stdout. Directories in the path are created if they are missing; a path that cannot hold a file — an existing directory, or a file sitting on its parent path — exits 2 and names it. |
--no-rescan | Fail rather than scanning when no analysis file is found. |
--concurrency <n> | How many worker threads the scan extracts its files on, as for aburi scan. No effect when an analysis file is read. |
--debug-resolution | Append a ## Call resolution table: each call site, what it resolved to, and for an unresolved one the reason and the candidates. The analysis file does not keep the reasons, so it always scans, and with --ir or --no-rescan it exits 2. |
--config <path> | Use a different config file. |
Without --ir, Aburi looks for aburi.ir.json in the output directory, walking up from the working directory to the workspace root. It scans when it finds nothing.
Several matches exit 2 and print the candidates so you can requalify. No match exits 1, and names how many files the analysis never read, since your match may sit in one of them. Ask about a file the analysis skipped and you get 3 instead. There is no answer to give, and "no matches" would claim more than the document can support. A file no analysis can name, such as a:notes.ts, also gets 3, with the name to change.
aburi explain submitOrder
aburi explain src/app/orders/actions.ts
aburi explain submitOrder --output docs/submitOrder.mdaburi vocab
aburi vocab list | effects | extkinds | plugins | who-owns <value> [--json] [--config <path>]Lists what a scan holds your plugins to: the core effect ids, and every effect id, extension kind, framework name and derivedBy prefix the plugins in your config declare. It loads the plugins the way aburi scan does, frameworkHints included, but scans nothing and runs no plugin code beyond importing it, so it works in a workspace with no sources and with no language plugin configured.
| Subcommand | Prints |
|---|---|
list | The plugins, effects and extkinds lists, plus Frameworks and derivedBy prefixes. |
effects | The core effect ids, then each plugin's effect ids and the prefixes it owns. |
extkinds | Each plugin's extension kinds, with their base kind, and the prefixes it owns. |
plugins | Each loaded plugin's name, version, type, and the config entry that loaded it. |
who-owns <value> | What owns the value in each vocabulary it belongs to, and how: listed by id, covered by a prefix, or core. |
$ aburi vocab effects
core db.read Database read
…
effects-nest x-nest:lifecycle.on-module-init NestJS OnModuleInit hook
effects-prisma (prefix x-prisma)
$ aburi vocab who-owns x-prisma:invoice.create
Vocabulary: effect
Plugin: effects-prisma (v0.6.0)
Type: effects
Listed in: effects "./plugins/effects-prisma.mjs"
Declaration: prefix x-prisma (provides.effectPrefixes[])Rows follow your config: language plugins, then framework plugins, then effect plugins, then the frameworkHints entries, each list in the order you wrote it. A value can belong to more than one vocabulary, such as an extension kind under a framework plugin's derivedBy prefix, and who-owns prints a block for each. A value nothing owns exits 1 and says so on stderr, with --json too.
| Flag | Effect |
|---|---|
--json | Print one JSON object instead: the lists the table shows, keyed as a plugin manifest names them (effects, effectPrefixes, extKinds, …), or { "value", "owners" } for who-owns. A core effect id has "owner": null. |
--config <path> | Use a different config file. |
Both flags can go before the subcommand or after it. With no config file found, no plugin loads: the lists hold the core effect ids alone, and stderr says so. A plugin that fails to load exits 3, as it does for aburi scan.
Programmatic use
@aburi/cli exports every command as a function, so your tests and tooling can drive it without spawning a process:
import { runCli, runInit, runScan, runDiff, runExplain, runVocab } from "@aburi/cli"
import { parseFailOn, evaluateFailOn, EXIT } from "@aburi/cli"
const code = await runCli({ argv, stdout, stderr, env, cwd })runCli returns the code rather than calling process.exit, leaving the decision to you. A CLI entry point should assign process.exitCode, as the aburi bin does: process.exit() can truncate output still being written to a pipe (aburi scan … | head). Like the bin, it should also listen for error on its output streams, ignore EPIPE, and keep any other error rather than throw it, setting a non-zero process.exitCode once the event loop drains (beforeExit). Node reports both a reader that closed early and a write the descriptor refused as that event; with no listener, or one that rethrows, the process ends at that write, before aburi diff removes its base worktree. The streams to listen on are the stdout and stderr it passes, unless they are in-memory captures, and process.stderr in any case, since the scan's log goes there whichever streams were passed.
The CLI spec holds the behavioural contract behind this page, including the reasoning for each exit code.