Tree-sitter CLI

A command-line tool for developing, testing, and using Tree-sitter parsers. Tree-sitter is a parser generator tool and incremental parsing library that builds concrete syntax trees for source files and efficiently updates them as files are edited. The CLI provides comprehensive functionality for parser development, testing, deployment, and usage workflows.

Package Information

• Package Name: tree-sitter-cli
• Package Type: cargo (Rust crate) / npm package
• Language: Rust
• Installation:
  • Via Cargo: cargo install --locked tree-sitter-cli
  • Via npm: npm install tree-sitter-cli
  • Via binary download from GitHub releases

Basic Usage

The CLI is invoked as tree-sitter with various subcommands:

# Initialize a new grammar project
tree-sitter init

# Generate parser from grammar
tree-sitter generate

# Build/compile the parser 
tree-sitter build

# Test the parser
tree-sitter test

# Parse files with the parser
tree-sitter parse input.txt

# Run syntax highlighting on files
tree-sitter highlight input.txt

# Execute tree-sitter queries
tree-sitter query queries.scm input.txt

Architecture

The tree-sitter-cli is built around these key components:

• Parser Generation: Transforms grammar.js files into C parsers using Node.js runtime
• Build System: Compiles parsers to native libraries or WASM modules using C/C++ compilers
• Testing Framework: Corpus-based testing with assertion syntax for parser validation
• Language Loader: Dynamic loading and configuration of multiple parser languages
• Query Engine: Tree-sitter query execution with capture groups and pattern matching
• Syntax Highlighting: Theme-based syntax highlighting with HTML/ANSI output
• Development Tools: Playground server, fuzzing, debugging, and visualization tools

This design enables complete parser development lifecycle management from initial grammar creation through deployment and usage.

Capabilities

Grammar Management

Commands for initializing, configuring, and managing grammar projects including interactive setup, version management, and project scaffolding.

tree-sitter init-config                    # Generate default config file
tree-sitter init [--update]                # Initialize grammar repository (alias: i)
tree-sitter version <version>              # Increment grammar version (alias: publish)

Grammar Management

Parser Generation and Building

Core functionality for generating parsers from grammar files and compiling them to native libraries or WASM modules.

tree-sitter generate [options] [grammar_path]      # Generate parser (aliases: gen, g)
tree-sitter build [options] [path]                 # Compile parser (alias: b)

Parser Generation

Testing and Validation

Comprehensive testing framework supporting corpus tests, syntax highlighting tests, tag tests, query validation, and fuzzing.

tree-sitter test [options]                 # Run parser tests (alias: t)
tree-sitter fuzz [options]                 # Fuzz test parser (alias: f)

Testing Framework

File Processing

Parse, highlight, query, and tag source files using Tree-sitter parsers with various output formats and processing options.

tree-sitter parse [options] <files...>     # Parse files (alias: p)
tree-sitter highlight [options] <files...> # Highlight files (alias: hi)
tree-sitter query <query_file> <files...>  # Query files (alias: q)
tree-sitter tags [options] <files...>      # Generate tags

File Processing

Development Tools

Development and debugging tools including web playground, language information display, and shell completion generation.

tree-sitter playground [options]           # Start web playground (aliases: play, pg, web-ui)
tree-sitter dump-languages [options]       # List known languages (alias: langs)
tree-sitter complete --shell <shell>       # Generate completions (alias: comp)

Development Tools

Global Options

Common options available across most commands:

--config-path <path>      # Use alternative config.json file
--help                    # Show help information
--version                 # Show version information

Configuration

Tree-sitter CLI uses a JSON configuration file typically located at ~/.config/tree-sitter/config.json. Generate a default configuration with:

tree-sitter init-config

The configuration includes:

• Language configurations: Parser locations, file associations, scopes
• Highlight themes: Color schemes for syntax highlighting
• Parse themes: Colors for parse tree visualization

Environment Variables

Key environment variables that affect CLI behavior:

• TREE_SITTER_ABI_VERSION: ABI version for parser generation (default: 15)
• TREE_SITTER_JS_RUNTIME: JavaScript runtime for parser generation (default: node)
• NO_COLOR: Disable colored output when set to "1"

Dependencies

Runtime dependencies required for various operations:

• Node.js: Required for parser generation (tree-sitter generate)
• C/C++ Compiler: Required for building and testing parsers
• Emscripten/Docker: Optional for WASM compilation