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:

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:

rust-analyzer-cli init-skill --workspace . --dir .agents/skills/rust-codebase-navigation/SKILL.md

As a CLI Tool

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:

[dependencies]
rust_analyzer_cli = "0.4.1"

Usage Guide

1. Start the Background Daemon

Before running queries, start the daemon from your workspace root:

rust-analyzer-cli daemon --workspace .

To check daemon & LSP indexing status:

rust-analyzer-cli status [--json]

To refresh/restart the rust-analyzer session:

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

rust-analyzer-cli symbol <name> [kind] [--exact] [--json]
# Example:
rust-analyzer-cli symbol LspClient struct --exact

Extract File Outline

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

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

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

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

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

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

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:

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. 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:

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 or Apache-2.0.

rust-analyzer-cli 0.5.0