0
# Tree-sitter CLI
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: tree-sitter-cli
7
- **Package Type**: cargo (Rust crate) / npm package
8
- **Language**: Rust
9
- **Installation**: 
10
  - Via Cargo: `cargo install --locked tree-sitter-cli`
11
  - Via npm: `npm install tree-sitter-cli`
12
  - Via binary download from GitHub releases
13

14
## Basic Usage
15

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

18
```bash
19
# Initialize a new grammar project
20
tree-sitter init
21

22
# Generate parser from grammar
23
tree-sitter generate
24

25
# Build/compile the parser 
26
tree-sitter build
27

28
# Test the parser
29
tree-sitter test
30

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

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

37
# Execute tree-sitter queries
38
tree-sitter query queries.scm input.txt
39
```
40

41
## Architecture
42

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

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

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

55
## Capabilities
56

57
### Grammar Management
58

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

61
```bash { .api }
62
tree-sitter init-config                    # Generate default config file
63
tree-sitter init [--update]                # Initialize grammar repository (alias: i)
64
tree-sitter version <version>              # Increment grammar version (alias: publish)
65
```
66

67
[Grammar Management](./grammar-management.md)
68

69
### Parser Generation and Building
70

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

73
```bash { .api }
74
tree-sitter generate [options] [grammar_path]      # Generate parser (aliases: gen, g)
75
tree-sitter build [options] [path]                 # Compile parser (alias: b)
76
```
77

78
[Parser Generation](./parser-generation.md)
79

80
### Testing and Validation
81

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

84
```bash { .api }
85
tree-sitter test [options]                 # Run parser tests (alias: t)
86
tree-sitter fuzz [options]                 # Fuzz test parser (alias: f)
87
```
88

89
[Testing Framework](./testing-framework.md)
90

91
### File Processing
92

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

95
```bash { .api }
96
tree-sitter parse [options] <files...>     # Parse files (alias: p)
97
tree-sitter highlight [options] <files...> # Highlight files (alias: hi)
98
tree-sitter query <query_file> <files...>  # Query files (alias: q)
99
tree-sitter tags [options] <files...>      # Generate tags
100
```
101

102
[File Processing](./file-processing.md)
103

104
### Development Tools
105

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

108
```bash { .api }
109
tree-sitter playground [options]           # Start web playground (aliases: play, pg, web-ui)
110
tree-sitter dump-languages [options]       # List known languages (alias: langs)
111
tree-sitter complete --shell <shell>       # Generate completions (alias: comp)
112
```
113

114
[Development Tools](./development-tools.md)
115

116
## Global Options
117

118
Common options available across most commands:
119

120
```bash { .api }
121
--config-path <path>      # Use alternative config.json file
122
--help                    # Show help information
123
--version                 # Show version information
124
```
125

126
## Configuration
127

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

130
```bash
131
tree-sitter init-config
132
```
133

134
The configuration includes:
135
- **Language configurations**: Parser locations, file associations, scopes
136
- **Highlight themes**: Color schemes for syntax highlighting
137
- **Parse themes**: Colors for parse tree visualization
138

139
## Environment Variables
140

141
Key environment variables that affect CLI behavior:
142

143
- `TREE_SITTER_ABI_VERSION`: ABI version for parser generation (default: 15)
144
- `TREE_SITTER_JS_RUNTIME`: JavaScript runtime for parser generation (default: node)
145
- `NO_COLOR`: Disable colored output when set to "1"
146

147
## Dependencies
148

149
Runtime dependencies required for various operations:
150
- **Node.js**: Required for parser generation (`tree-sitter generate`)
151
- **C/C++ Compiler**: Required for building and testing parsers
152
- **Emscripten/Docker**: Optional for WASM compilation