CLI Reference

May 24, 2026 · View on GitHub

Complete command-line interface reference for Tree-sitter Analyzer.

Table of Contents

Basic Usage

uv run tree-sitter-analyzer <file_path> [options]

Agent Workflow Pack

Agents can ask for a ready-to-run SMART workflow command pack before opening a new queue item:

uv run tree-sitter-analyzer agent-workflow --format json
uv run tree-sitter-analyzer agent-workflow tree_sitter_analyzer/cli_main.py --format json

The JSON and TOON responses include current_phase, phase_order, current_step, and recommended_commands, so agents can tell whether they should start at project setup (set) or jump directly to targeted file analysis (analyze) for an existing queue head. JSON mode also includes per-step handoff metadata (to, condition, goal, transition_command) so callers can assert exact queue transitions. TOON includes a compact handoffs: section with one readable rule per step.

When a target path is supplied, agent_summary.queue_ledger_command gives the scoped change-impact command that reports current-queue and out-of-scope dirty counts.

When the set phase is chosen, the pack now also recommends agent-skills --format json and parser-readiness --format json so the first queue cycle starts with skill availability and language-plugin readiness checked before file mapping.

Agent Skills Inventory

Project-local skills under .agents/skills can be inspected through the same CLI surface as code-analysis tools. The inventory reports each skill's trigger text, read order, support files, scripts, context needs, side effects, and gaps such as missing completion or acceptance guidance. It also returns a validation summary with status, blocking/caution/optional gap counts, and the next metadata fix:

uv run tree-sitter-analyzer agent-skills --format json
uv run tree-sitter-analyzer agent-skills --format toon
uv run tree-sitter-analyzer --agent-skills --agent-skills-root .agents/skills --format json

Parser Readiness Advisor

Language roadmap work can be inspected before writing a new plugin. The parser readiness advisor compares local parser dependencies, plugin entry points, loader mappings, tests, golden masters, and installed parser-package artifacts such as package version, project/maintenance URLs, binding ABI, parser semantic version, packaged grammar.json, and scanner files:

uv run tree-sitter-analyzer parser-readiness --format json
uv run tree-sitter-analyzer parser-readiness swift --format json
uv run tree-sitter-analyzer --parser-readiness --parser-readiness-include-supported --format toon

Agent-Friendly MCP Aliases

These aliases are equivalent to the flag-based MCP mirror commands and exist so agents can call tools in the same order they think about the workflow:

uv run tree-sitter-analyzer agent-skills --format json
uv run tree-sitter-analyzer parser-readiness swift --format json
uv run tree-sitter-analyzer file-health tree_sitter_analyzer/cli_main.py --format json
uv run tree-sitter-analyzer safe-to-edit tree_sitter_analyzer/cli_main.py --edit-type refactor --format json
uv run tree-sitter-analyzer refactor tree_sitter_analyzer/cli_main.py --format json
uv run tree-sitter-analyzer smart-context tree_sitter_analyzer/cli_main.py --format json
uv run tree-sitter-analyzer change-impact --agent-summary-only --format json
uv run tree-sitter-analyzer change-impact --change-impact-mode staged --change-impact-no-tests --format json
uv run tree-sitter-analyzer change-impact --change-impact-scope tree_sitter_analyzer/cli_main.py --agent-summary-only --format json
uv run tree-sitter-analyzer project-health --max-files 5 --format json
uv run tree-sitter-analyzer --dependencies summary --format json
uv run tree-sitter-analyzer tree_sitter_analyzer/cli_main.py --dependencies file_deps --format json

Use project-health --max-files <n> when working inside a noisy repository. It limits detailed file rows, top targets, and the agent backlog so the next queue head stays compact and intentional.

file-health JSON and TOON responses include an agent_summary with the weakest dimension and score plus the first actionable smell, its line, symbol, and detail when those can be inferred, so an agent can jump straight to the right function before deciding whether to invoke refactor.

Scoped change-impact responses include a queue_ledger with scoped changed counts, out-of-scope dirty counts, short previews, and a compact handoff string. Use it when the working tree is noisy and the current queue is only a few paths.

Global Options

OptionDescription
--helpShow help message
--show-supported-languagesShow supported languages
--language <lang>Specify programming language (auto-detected by default)
--output-format <format>Output format: json, text

Code Structure Analysis

Summary Analysis

# Quick summary (file scale and overview)
uv run tree-sitter-analyzer examples/BigService.java --summary

Structure Analysis

# Detailed structure (all elements)
uv run tree-sitter-analyzer examples/BigService.java --structure

Advanced Analysis

# Advanced analysis with complexity metrics
uv run tree-sitter-analyzer examples/BigService.java --advanced

# With JSON output
uv run tree-sitter-analyzer examples/BigService.java --advanced --output-format json

# With text output
uv run tree-sitter-analyzer examples/BigService.java --advanced --output-format text

Table Output

# Full table (comprehensive)
uv run tree-sitter-analyzer examples/BigService.java --table full

# Compact table (abbreviated)
uv run tree-sitter-analyzer examples/BigService.java --table compact

# CSV format (machine-readable)
uv run tree-sitter-analyzer examples/BigService.java --table csv

Partial Code Extraction

# Extract specific line range
uv run tree-sitter-analyzer examples/BigService.java --partial-read --start-line 93 --end-line 106

# Extract from start line to end of file
uv run tree-sitter-analyzer examples/BigService.java --partial-read --start-line 100

Language-Specific Examples

HTML/CSS Analysis

# HTML analysis
uv run tree-sitter-analyzer examples/comprehensive_sample.html --table full
uv run tree-sitter-analyzer examples/comprehensive_sample.html --structure

# CSS analysis
uv run tree-sitter-analyzer examples/comprehensive_sample.css --table full
uv run tree-sitter-analyzer examples/comprehensive_sample.css --advanced --output-format text

SQL Database Analysis

# Full table output
uv run tree-sitter-analyzer examples/sample_database.sql --table full

# Compact summary
uv run tree-sitter-analyzer examples/sample_database.sql --table compact

# CSV for export
uv run tree-sitter-analyzer examples/sample_database.sql --table csv

# Advanced text analysis
uv run tree-sitter-analyzer examples/sample_database.sql --advanced --output-format text

Markdown Analysis

# Analyze markdown structure
uv run tree-sitter-analyzer docs/README.md --table full

# View document structure
uv run tree-sitter-analyzer docs/README.md --structure

Query and Filter Commands

Query Specific Elements

# Query methods
uv run tree-sitter-analyzer examples/BigService.java --query-key methods

# Query classes
uv run tree-sitter-analyzer examples/BigService.java --query-key classes

# Query functions (for Python, JavaScript)
uv run tree-sitter-analyzer examples/sample.py --query-key functions

# Query imports
uv run tree-sitter-analyzer examples/BigService.java --query-key imports

Filter Query Results

# Find specific method by name
uv run tree-sitter-analyzer examples/BigService.java --query-key methods --filter "name=main"

# Pattern matching (wildcard)
uv run tree-sitter-analyzer examples/BigService.java --query-key methods --filter "name=~auth*"

# Find public methods with no parameters
uv run tree-sitter-analyzer examples/BigService.java --query-key methods --filter "params=0,public=true"

# Find static methods
uv run tree-sitter-analyzer examples/BigService.java --query-key methods --filter "static=true"

View Filter Help

uv run tree-sitter-analyzer --filter-help

⚠️ Note: --table and --query-key are mutually exclusive. Use --query-key with --filter for filtering.

File System Operations

List Files (fd-based)

# List all files in current directory
uv run list-files .

# Filter by extension
uv run list-files . --extensions java

# Filter by pattern and type
uv run list-files . --pattern "test_*" --extensions py --types f

# Filter by size and modification time
uv run list-files . --types f --size "+1k" --changed-within "1week"

# Exclude directories
uv run list-files . --exclude "node_modules" --exclude "__pycache__"

Search Content (ripgrep-based)

# Basic content search
uv run search-content --roots . --query "class.*extends" --include-globs "*.java"

# Search with context
uv run search-content --roots tests --query "TODO|FIXME" --context-before 2 --context-after 2

# Case-insensitive search
uv run search-content --files examples/BigService.java --query "public.*method" --case insensitive

# Search multiple directories
uv run search-content --roots src tests --query "import" --include-globs "*.py"

Two-Stage Search (fd + ripgrep)

# Find files then search content
uv run find-and-grep --roots . --query "@SpringBootApplication" --extensions java

# With file and content limits
uv run find-and-grep --roots examples --query "import.*SQLException" --extensions java --file-limit 10 --max-count 5

# With JSON output
uv run find-and-grep --roots . --query "public.*static.*void" --extensions java --types f --size "+1k" --output-format json

Information Commands

Help and Version

# Show help
uv run tree-sitter-analyzer --help

# Show supported languages
uv run tree-sitter-analyzer --show-supported-languages

Language Support Information

# List supported query keys
uv run tree-sitter-analyzer --list-queries

# Show supported languages
uv run tree-sitter-analyzer --show-supported-languages

# Show supported file extensions
uv run tree-sitter-analyzer --show-supported-extensions

# Show common queries for each language
uv run tree-sitter-analyzer --show-common-queries

# Show query language support matrix
uv run tree-sitter-analyzer --show-query-languages

SQL Cross-Platform Commands

# Show current platform SQL parsing capabilities
uv run tree-sitter-analyzer --sql-platform-info

# Record a custom SQL parsing profile
uv run tree-sitter-analyzer --record-sql-profile

# Compare two SQL profiles
uv run tree-sitter-analyzer --compare-sql-profiles windows-3.13 linux-3.10

Output Formats

JSON Output

# Code analysis to JSON
uv run tree-sitter-analyzer examples/sample.py --advanced --output-format json

# Search results to JSON
uv run find-and-grep --roots . --query "def " --extensions py --output-format json

Text Output

# Human-readable text output
uv run tree-sitter-analyzer examples/sample.py --advanced --output-format text

Table Formats

FormatDescriptionUse Case
fullComprehensive table with all detailsDetailed analysis
compactAbbreviated summaryQuick overview
csvComma-separated valuesExport to spreadsheet

Filter Syntax

Exact Match

--filter "name=main"          # Method named exactly "main"
--filter "visibility=public"  # Public visibility
--filter "params=2"           # Methods with 2 parameters

Pattern Match (Wildcard)

--filter "name=~get*"         # Names starting with "get"
--filter "name=~*Service"     # Names ending with "Service"
--filter "name=~*auth*"       # Names containing "auth"

Boolean Filters

--filter "public=true"        # Public methods
--filter "static=true"        # Static methods
--filter "async=true"         # Async methods

Compound Filters

# Multiple conditions (AND)
--filter "public=true,static=true"

# Combine with pattern
--filter "name=~get*,public=true"

# Multiple conditions
--filter "params=0,public=true,static=false"

Available Filter Fields

FieldDescriptionExample
nameElement namename=main, name=~get*
visibilityVisibility modifiervisibility=public
publicIs publicpublic=true
privateIs privateprivate=true
protectedIs protectedprotected=true
staticIs staticstatic=true
asyncIs asyncasync=true
paramsParameter countparams=2, params=0

Security Notes

Tree-sitter Analyzer enforces security boundaries:

  • Files outside the project directory are inaccessible
  • Path traversal attacks are automatically prevented
  • Invalid parameter combinations are rejected with clear error messages
# ✅ Allowed: File within project
uv run tree-sitter-analyzer examples/BigService.java --advanced

# ❌ Denied: File outside project boundary
# uv run tree-sitter-analyzer /etc/passwd --advanced
# Error: Access denied - file outside project boundary

Examples

Complete Workflow Example

# 1. Check what files exist
uv run list-files . --extensions java --types f

# 2. Search for specific content
uv run search-content --roots . --query "class.*Service" --include-globs "*.java"

# 3. Analyze found file
uv run tree-sitter-analyzer src/UserService.java --summary

# 4. Get detailed structure
uv run tree-sitter-analyzer src/UserService.java --table full

# 5. Extract specific method
uv run tree-sitter-analyzer src/UserService.java --query-key methods --filter "name=authenticate"

Token-Optimized Analysis (for large files)

# 1. Check file scale first
uv run tree-sitter-analyzer large_file.java --summary

# 2. If large, use compact format
uv run tree-sitter-analyzer large_file.java --table compact

# 3. Query specific elements instead of full analysis
uv run tree-sitter-analyzer large_file.java --query-key methods --filter "public=true"

# 4. Extract only the lines you need
uv run tree-sitter-analyzer large_file.java --partial-read --start-line 100 --end-line 150