CLI reference

Choose the project#

Run these commands from the indexed project's root. Most accept an optional project path; the command's --help lists the argument order. Replace example symbols and file paths with ones from your project.

arbor setup
arbor status
arbor index --no-cache

setup initializes and indexes. status scans the project again and prints file, node and edge counts. index --no-cache requests a full rebuild; use index for a normal refresh.

Find relevant code#

arbor map . --tokens 2000 --exclude-test
arbor query "parse|validate" --limit 20
arbor file-graph src/parser.py
arbor inspect parse_file

map

A ranked repository outline within an estimated token budget. --exclude-test filters test, spec, fixture, and mock files.

query

Literal substring search over symbol names. Quote the | separator to search alternatives without invoking a shell pipe.

file-graph

The symbols and call edges associated with one source file.

inspect

Details for a symbol name or node ID, useful for checking that you have found the intended definition.

callers, callees and inspect print absolute paths with line numbers; the examples on this page shorten them. Several files may define the same name, so check the reported location before relying on a result. Trace dependencies shows how to pick one definition.

Trace dependencies#

arbor callers parse_file
arbor callees parse_file
arbor path parse_project parse_file
arbor refactor parse_file --depth 3 --why

callers and callees show direct relationships. path follows a directed call-graph path between two symbols. refactor explores impact to a chosen depth; --why includes reasoning about affected nodes.

The depth is a traversal limit, not a guarantee that every runtime dependency is represented. Read the graph guide alongside the result.

One answer per definition

When several definitions share a name, callers and callees answer for each one and never merge the lists. Up to six are shown, most connected first. In a project where src/parser.py and src/legacy.py both define parse_file:

$ arbor callers parse_file
'parse_file' matches 2 definitions. Callers of each:

Python function parse_file (…/src/parser.py:11) — 1 callers
    function parse_project (…/src/project.py:4)

Python function parse_file (…/src/legacy.py:1) — 1 callers
    function load_legacy (…/src/legacy.py:5)

Pick one with a module path (jobs::enqueue), a type (Type.method) or a file (src/jobs.rs:enqueue).

$ arbor callers src/parser.py:parse_file
Callers of 'src/parser.py:parse_file' (1):

  function parse_project (…/src/project.py:4)

The file form matches the end of the path in any language, so parser.py:parse_file works too. It is a plain suffix, so it also matches myparser.py. A module or type path works in any language as well: parser::parse_file picks the definition in a file or folder named parser, and Queue::enqueue picks the enqueue method of Queue. The hint also offers Type.method, which v3.0.3 answers with Symbol 'Type.method' not found; write Type::method instead.

With --json, read the matches array: it has one entry per definition, up to six, while the top-level callers list holds only the first definition's callers.

An empty answer

No callers does not mean unused. When a single definition has no callers, v3.0.3 says so in the output:

$ arbor callers main
No callers found for 'main' — Python function main (…/src/app.py:4)
Not proof that nothing does: calls through trait objects, function pointers, callbacks, reflection or generated code aren't followed. Confirm with a text search before treating this symbol as unused or changing its signature.

With --json, the same text arrives as a note field next to an empty callers list.

Review Git changes#

arbor diff
arbor diff --staged
arbor diff --base main
arbor check --max-blast-radius 30 --markdown

diff reports impact for local Git changes, and each run starts by saying what it compared:

arbor diff

Compared: uncommitted changes against HEAD

arbor diff --staged

Compared: staged changes against HEAD

arbor diff --base main

Compared: changes since this branch left main (merge base d4be9b0)

The default includes untracked files; --staged does not. --base covers committed and uncommitted work since the merge base, as a pull request shows it, and can't be combined with --staged. v3.0.3 doesn't run git fetch, so --base origin/main uses your local copy of that branch; fetch first. check and summary accept both flags.

Change Impact Preview
Compared: changes since this branch left main (merge base d4be9b0)

Changed files:
  • src/parser.py (modified)

Symbols: 1 modified · 0 new

Impact of the modified symbols (new code has no existing callers):
  • 1 direct callers
  • 1 indirect callers
  • 1 API entrypoints affected
  • 2 files likely require updates
  • 4 impacted nodes total

Only modified symbols carry a blast radius. New symbols are listed by name, as in new: load_many, because nothing calls them yet. When tests call the change, a line reads N tests exercise the modified code (worth running; not counted as impact). Whitespace-only edits are ignored, and so are files under target, dist, build or generated folders and a few generated suffixes such as .pb.go and .g.dart.

check can exit with a failure status when the blast radius exceeds the threshold, an entrypoint is affected, or indirect callers exceed half the threshold. The value 30 is an example; the default is 25. In v3.0.3, the Markdown failure message still says the blast-radius threshold was exceeded even when another rule triggered the failure. Read the entrypoint and indirect-caller counts as well.

Help and machine-readable output#

arbor refactor parse_file --json
arbor map --json
arbor diff --help

Flags belong to individual commands. For example, refactor, map, diff, callers and receipt show support --json; query in v3.0.3 does not. diff --json includes compared, modified_symbols, new_symbols and impact.tests_exercising. Use arbor <command> --help for the executable you installed.