Command-Line Interface (CLI)
Relevant source files
The following files were used as context for generating this wiki page:
The Arbor Command-Line Interface (CLI) serves as the primary gateway for developers to interact with the Arbor graph-native intelligence engine. It facilitates the transformation of raw source code into a semantic dependency graph, enabling advanced operations such as impact analysis, codebase querying, and AI-assisted navigation through the Model Context Protocol (MCP).
The CLI is designed to be local-first, providing deterministic and explainable answers about code execution paths, callers, callees, and cross-file relationships. It supports a wide array of languages including Rust, TypeScript, Python, and Java, among others.
Sources: crates/arbor-cli/README.md:1-12, README.md:16-25
Architecture and Command Structure
The CLI is built using the clap library for command-line argument parsing and tokio for asynchronous execution. The entry point handles global configuration—such as verbosity—and dispatches specialized logic to the commands module.
Core Command Set
| Command | Functionality | Key Parameters |
|---|---|---|
init | Initializes the .arbor configuration directory and creates a default config.json. | path (default: .) |
index | Scans the codebase, extracts nodes, and builds the semantic graph. | path, --output, --follow-symlinks, --no-cache |
query | Performs a search within the extracted code graph for specific symbols. | query, --limit |
refactor | Analyzes the "blast radius" or impact of changing a specific code node. | target, --depth, --why, --json |
explain | Provides graph-backed context for explaining specific code paths. | question, --tokens, --why, --json |
bridge | Starts the "Agentic Bridge" which combines the MCP server and optional Visualizer. | path, --viz, --follow-symlinks |
serve | Launches the Arbor WebSocket/RPC server for external client connections. | --port, --headless, path |
Sources: crates/arbor-cli/src/main.rs:25-167, crates/arbor-cli/src/commands.rs:17-48
System Initialization Flow
When a user executes arbor init, the system prepares the environment for indexing. It checks for the existence of an .arbor directory and populates it with a standard configuration specifying supported languages and ignore patterns.
The default configuration includes standard ignores such as node_modules, target, and __pycache__.
Sources: crates/arbor-cli/src/commands.rs:17-41
Codebase Indexing and Status
The index command is the engine's core, utilizing the arbor_watcher crate to traverse directories. It provides real-time feedback through a progress spinner and outputs a summary of files indexed, nodes extracted, and any parse errors encountered.
Indexing Logic
- Cache Determination: Unless
--no-cacheis specified, the indexer looks for.arbor/cache. - File Scanning: Recursively walks the directory (optionally following symlinks).
- Extraction: Identifies parseable definitions (functions, classes, etc.) in supported file extensions.
- Validation: Warns if no nodes were extracted, suggesting checks for
.gitignoreor supported extensions.
Sources: crates/arbor-cli/src/commands.rs:44-100
Extension Summary
The arbor status command provides a statistical breakdown of the indexed graph, including node/edge counts and file extension distribution.
Impact Analysis (Refactor Command)
One of the CLI's most advanced features is the refactor command, which simulates a "blast radius" for proposed changes. It categorizes nodes by their architectural roles:
- Entry Point: No internal callers; calls others (API/CLI endpoints).
- Utility: High caller count; few dependencies.
- Core Logic: Sits in the middle; high connectivity.
- Isolated: No callers or dependencies detected.
Sources: README.md:126-133, crates/arbor-cli/src/commands.rs:317-535
Impact Severity Classification
| Severity | Description |
|---|---|
| Direct | Immediate callers/dependencies (1 hop). |
| Transitive | Indirectly affected nodes (2-3 hops). |
| Distant | Nodes 4+ hops away in the call graph. |
Sources: CHANGELOG.md:11-13
Similarity Suggestions
If a user provides a symbol that does not exactly match the graph, the CLI utilizes Jaro-Winkler similarity to suggest corrections, such as matching autth to auth.
Sources: README.md:10-11, crates/arbor-cli/src/commands.rs:538-592
AI Integration and The Agentic Bridge
The bridge command facilitates AI interaction by running a Model Context Protocol (MCP) server over stdio. This allows LLMs to query the graph directly for pathfinding or impact analysis.
Bridge Component Flow
The bridge manages multiple background tasks to ensure both the AI and the developer stay in sync.
Spotlight Capability
When an AI agent queries a node via the MCP tool get_logic_path or analyze_impact, the McpServer triggers a "spotlight" event. This event is sent via the SyncServer to the visualizer, causing it to automatically highlight the specific file and line the AI is currently analyzing.
Sources: crates/arbor-mcp/src/lib.rs:50-69, crates/arbor-mcp/src/lib.rs:184-185
Visualizer Integration
The CLI provides multiple ways to launch the graphical interface. The viz command starts the full stack (RPC and Sync servers) before launching the visualizer application.
Visualizer Launch Priority
- Bundled Executable: Looks for
arbor_visualizer/visualizer.exe(Windows),.app(macOS), or binary (Linux) relative to the arbor binary. - Dev Mode: If source code is present, it attempts to launch via
flutter runin thevisualizerdirectory.
Sources: crates/arbor-cli/src/commands.rs:159-201
Conclusion
The Arbor CLI provides a high-performance, local-first toolkit for managing code as a property graph. By integrating indexing, impact analysis, and AI-protocol bridges into a single binary, it enables developers and AI agents to navigate complex architectures with structural certainty rather than probabilistic guesses.