# rust-analyzer-cli
Compiler-accurate Rust codebase navigation powered by `rust-analyzer` LSP and an embedded HTTP daemon.
`rust-analyzer-cli` is dual-structured as both a **CLI tool** and a **Rust Library** (`rust_analyzer_cli`), enabling developers, automation tools, and Rust programs to perform fast, compiler-accurate symbol search, document outline extraction, definition lookup, call hierarchy analysis, and compilation checks.
---
## Features
- 🚀 **Background Daemon & Persistent LSP Session**: Spawns `rust-analyzer` via JSON-RPC stdio and serves an embedded Axum HTTP REST server (default port `60094`).
- 🔍 **Workspace Symbol Search**: Search for structs, enums, functions, traits, and variables across the entire workspace.
- 📜 **Document Outline**: Extract hierarchical document symbol outlines for any `.rs` file.
- 🎯 **Go to Definition**: Jump directly to exact symbol definitions by file, line, and column.
- 💬 **Hover Documentation**: Read Rust type information and `///` documentation at a file position.
- 📞 **Call Hierarchy & References**: Query incoming/outgoing call chains and symbol reference locations.
- 🧬 **Type Hierarchy**: Traverse supertypes and subtypes.
- 🛠 **Cargo Check Integration**: Run `cargo check` and parse structured compiler diagnostics.
- 🤖 **Automation Friendly**: Supports human-readable CLI outputs and `--json` structured formatting.
---
## Installation
### Install and Initialize the Project Skill
Install the published crate, then run the initialization command from the
target project workspace:
```powershell
cargo install rust-analyzer-cli
rust-analyzer-cli init-skill --workspace .
```
The second command writes the skill to
`.agents/skills/rust-codebase-navigation/SKILL.md`. Tools can then read this
file and use the documented commands to inspect the Rust project.
Requirements:
- Rust and Cargo must be installed and available in `PATH`.
- `rust-analyzer` must be installed and available in `PATH`.
To write the skill to another project-relative path:
```powershell
rust-analyzer-cli init-skill --workspace . --dir .agents/skills/rust-codebase-navigation/SKILL.md
```
### As a CLI Tool
```bash
cargo install rust-analyzer-cli
```
*Prerequisite*: Ensure `rust-analyzer` is installed and available in your system `PATH`.
### As a Rust Library
Add `rust_analyzer_cli` to your project's `Cargo.toml`:
```toml
[dependencies]
rust_analyzer_cli = "0.4.1"
```
---
## Usage Guide
### 1. Start the Background Daemon
Before running queries, start the daemon from your workspace root:
```bash
rust-analyzer-cli daemon --workspace .
```
To check daemon & LSP indexing status:
```bash
rust-analyzer-cli status [--json]
```
To refresh/restart the `rust-analyzer` session:
```bash
rust-analyzer-cli refresh [--json]
```
Query commands require the daemon to be running. File paths are interpreted
from the workspace used to start the daemon, and line/column positions are
1-based. In `--json` mode stdout contains only machine-readable JSON. A valid
query with no result returns an empty array or `null`; this is not an error.
---
### 2. Core Commands
#### Search Workspace Symbols
```bash
rust-analyzer-cli symbol <name> [kind] [--exact] [--json]
# Example:
rust-analyzer-cli symbol LspClient struct --exact
```
#### Extract File Outline
```bash
rust-analyzer-cli outline --file <path> [-o <output_file>] [--json]
rust-analyzer-cli outline --file-list <path1,path2> [--json]
# Example:
rust-analyzer-cli outline --file src/main.rs
```
Provide exactly one of `--file` and `--file-list`. With `--body`, source output
is limited to 100 lines by default; use `--max-lines 0` for unlimited output.
When `--json --output <path>` is used, the outline JSON is written to the file
and stdout contains a JSON success summary with the output path.
#### Go to Definition
```bash
rust-analyzer-cli definition --file <path> --line <line> --col <col> [--json]
# Example:
rust-analyzer-cli definition --file src/main.rs --line 13 --col 10
```
Use 1-based line and column numbers. The optional body output uses the same
100-line default; the `body` command reports truncation in human-readable mode.
#### Inspect Source Body
```bash
rust-analyzer-cli body --file <path> --line <line> --col <col> [--max-lines <n>] [--json]
# Example:
rust-analyzer-cli body --file src/main.rs --line 15 --col 10 --max-lines 50
```
The default body limit is 100 lines. A truncation message includes both the
displayed and total line counts; `--max-lines 0` disables the limit.
#### Hover Documentation
```bash
rust-analyzer-cli hover --file <path> --line <line> --col <col> [--json]
# Example:
rust-analyzer-cli hover --file src/main.rs --line 15 --col 10
```
#### References & Call Hierarchy
```bash
rust-analyzer-cli cursor --file <path> --line <line> --col <col> [--mode incoming|outgoing|references] [--depth <n>] [--json]
# Example:
rust-analyzer-cli cursor --file src/main.rs --line 25 --col 8 --mode incoming
```
`--depth` defaults to 1 and controls call-hierarchy traversal. The
`references` mode uses the direct LSP reference query, so depth does not add
additional traversal in that mode.
#### Type Hierarchy
```bash
rust-analyzer-cli type-hierarchy --file <path> --line <line> --col <col> [--mode supertypes|subtypes] [--depth <n>] [--json]
```
`--depth` defaults to 1 and controls the number of supertype or subtype levels
returned. Results are de-duplicated when a hierarchy contains cycles or shared
parents.
#### Cargo Check Verification
```bash
rust-analyzer-cli check [--target <target>] [--json]
```
When compilation fails, the command includes Cargo diagnostics and, when no
structured compiler diagnostic is available, Cargo's stderr failure message.
---
## Using as a Rust Library
You can embed the HTTP server or interact with data types directly in your Rust applications:
```rust
use rust_analyzer_cli::daemon::server::start_daemon_server;
use rust_analyzer_cli::lsp::types::*;
use std::path::PathBuf;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let workspace = PathBuf::from(".");
let port = 60094;
// Start daemon server asynchronously
tokio::spawn(async move {
start_daemon_server(workspace, port).await.unwrap();
});
Ok(())
}
```
---
## Project Skill
The navigation skill definition is included at [.agents/skills/rust-codebase-navigation/SKILL.md](.agents/skills/rust-codebase-navigation/SKILL.md). The `init-skill` command copies it into any project workspace.
For a project that already has this repository checked out, initialize the skill with Cargo during development:
```powershell
cargo run -- init-skill --workspace .
```
For a globally installed binary, use `rust-analyzer-cli init-skill --workspace .` as shown above.
---
## License
Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE).