Getting started
Five minutes from install to your first semantic diff. You need Node.js 24 or newer and a git repository.
1. Install
Install the CLI and a language plugin, then add framework and effects plugins for whatever your project uses. Supported stacks lists them all.
pnpm add -D @aburi/cli @aburi/lang-typescript @aburi/framework-next @aburi/framework-reactnpm install -D @aburi/cli @aburi/lang-typescript @aburi/framework-next @aburi/framework-reactyarn add -D @aburi/cli @aburi/lang-typescript @aburi/framework-next @aburi/framework-reactbun add -D @aburi/cli @aburi/lang-typescript @aburi/framework-next @aburi/framework-reactThe rest of this page writes the commands bare. Run them through whichever package manager you installed with:
pnpm exec aburi <command>npx aburi <command>yarn aburi <command>bunx aburi <command>2. Create a config
aburi initinit looks at your repository, works out the workspace layout, languages, and frameworks, and reports what it found:
✓ Wrote /home/you/shop/aburi.json
managers: pnpm
languages: ts
frameworks: nextjs, react
components: 1The file it wrote names the plugins to load and the components it detected:
{
"$schema": "https://aburi.dev/schema/aburi.config.v1.json",
"languages": ["lang-typescript"],
"frameworks": ["framework-next", "framework-react"],
"components": [
{
"id": "storefront",
"name": "storefront",
"roots": ["apps/storefront"],
"languages": ["ts"],
"frameworks": ["nextjs", "react"]
}
]
}Everything else has a default, and Configuration covers the knobs you may want later.
TIP
aburi init --with-suggestions adds a comment naming the plugin packages it found in your project but not in your dependencies.
3. Scan
aburi scanThe first line is the symbol census, the second says how much of the call graph resolved, and the arrows name what was written:
184 kept · 63 dropped · 212 files
calls 1043 · resolved 917 · unresolved 126 (external 108 · dynamic 14 · no-match 4)
→ /home/you/shop/.aburi/aburi.ir.json
→ /home/you/shop/.aburi/workspace.mdFour things land in .aburi/, and the directory ignores itself, so nothing needs adding to your own .gitignore.
| File | What it is |
|---|---|
.gitignore | Written by the scan that creates .aburi/. It ignores everything in the directory, itself included. |
aburi.ir.json | The analysis itself, as JSON. Everything else derives from it. |
workspace.md | One page covering the whole repository: components, their languages and frameworks, the effect surface. |
components/*.md | Per-component detail. Every kept symbol with its boundaries, rules, and effects. |
Open workspace.md first. On a codebase you have never seen, it is the fastest map you will get.
4. Diff two revisions
aburi diff main..HEAD --fail-on 'removed,changed:>20'The glyph line is the summary — added, removed, changed, moved, moved+changed:
+2 -1 ~3 ↔0 ⤴0
calls 1043 · resolved 917 · unresolved 126 (external 108 · dynamic 14 · no-match 4)
→ /home/you/shop/.aburi/diff.md.aburi/diff.md is the report you hand to a reviewer, and .aburi/diff.json sits beside it. A tripped --fail-on clause prints the reason on stderr, with the Symbols that tripped it, and exits 3, which is what CI gates on:
--fail-on removed tripped (observed: 1 removed)
ts:src/billing/legacy.ts#refundInvoiceSee CI integration.
Quote the --fail-on value
> is a redirect in every shell. --fail-on changed:>5 writes a file called 5. --fail-on 'changed:>5' sets a threshold.
Reading the report explains what comes out.
5. Zoom in on one symbol
When the diff flags something and you want the full picture:
aburi explain submitOrderThe symbol's Markdown goes to stdout, so you can pipe it into a pager or a file:
# `submitOrder` *(function)*
**Component**: storefront
**File**: `apps/storefront/src/app/orders/actions.ts:5-12`
**Visibility**: public
**Language**: ts
## Signature
`(cart: Cart) → Promise<Order>` throws `EmptyCart` ⚡async
## Rules
- guard: `cart.items.length === 0` (L6)
- throw: `EmptyCart` (L7)
## Calls
- `EmptyCart` (L7)
- `createOrder` (L9)
- `sendReceipt` (L10)
## Derived by
- `export-keyword`
## Fingerprint
- api: `94f035a1f334`
- logic: `708d436dac4a`
- syntax: `d64c00d2efc8`Sections for decorators, effects, and callers appear whenever the analysis has them, and the component line whenever a component's roots hold the file. Pass a symbol name, a file path, or a full symbol id — Aburi works out which one you meant. --output <path> writes the Markdown to a file instead.
Where to go next
- Reading the report explains each section.
- Configuration covers every field of
aburi.json. - CI integration runs this on every pull request.
- CLI reference lists every flag and exit code.