0
# CLI Tool
1

2
Complete command-line interface for Python static type checking with extensive configuration options and output formats.
3

4
## Capabilities
5

6
### Main Command
7

8
Primary interface for static type analysis of Python code.
9

10
```bash { .api }
11
pyright [options] files...
12
```
13

14
### Analysis Options
15

16
Control the scope and behavior of type analysis.
17

18
```bash { .api }
19
--createstub <IMPORT>
20
# Create type stub file(s) for the specified import
21

22
--level <LEVEL>  
23
# Set minimum diagnostic level: "error" or "warning"
24

25
--skipunannotated
26
# Skip analysis of functions with no type annotations
27

28
--verifytypes <PACKAGE>
29
# Verify type completeness of a py.typed package
30

31
--ignoreexternal
32
# Ignore external imports for --verifytypes (only valid with --verifytypes)
33
```
34

35
**Usage Examples:**
36

37
```bash
38
# Create type stubs for a package
39
pyright --createstub requests
40

41
# Only show errors, hide warnings
42
pyright --level error src/
43

44
# Skip unannotated functions
45
pyright --skipunannotated
46

47
# Verify package type completeness
48
pyright --verifytypes mypackage
49
```
50

51
### Python Environment Options
52

53
Configure the Python environment and interpreter settings.
54

55
```bash { .api }
56
--pythonplatform <PLATFORM>
57
# Analyze for specific platform: "Darwin", "Linux", or "Windows"
58

59
--pythonpath <FILE>
60
# Path to the Python interpreter executable
61

62
--pythonversion <VERSION>
63
# Analyze for specific Python version: "3.3", "3.4", "3.7", "3.8", "3.9", "3.10", "3.11", etc.
64

65
-v, --venvpath <DIRECTORY>
66
# Directory that contains virtual environments
67

68
-t, --typeshedpath <DIRECTORY>
69
# Use typeshed type stubs at this location
70
```
71

72
**Usage Examples:**
73

74
```bash
75
# Check for Linux compatibility
76
pyright --pythonplatform Linux
77

78
# Use specific Python version
79
pyright --pythonversion 3.9
80

81
# Set virtual environment path
82
pyright --venvpath ./venvs
83

84
# Use custom typeshed location
85
pyright --typeshedpath ./custom-typeshed
86
```
87

88
### Project Configuration Options
89

90
Specify project files and configuration settings.
91

92
```bash { .api }
93
-p, --project <FILE OR DIRECTORY>
94
# Use configuration file at this location
95

96
files...
97
# Python files to analyze (default positional argument)
98

99
-
100
# Read file list from stdin
101
```
102

103
**Usage Examples:**
104

105
```bash
106
# Use specific config file
107
pyright --project ./myconfig.json
108

109
# Analyze specific files
110
pyright src/main.py tests/test_main.py
111

112
# Read file list from stdin
113
echo "src/main.py src/utils.py" | pyright -
114
```
115

116
### Output Options
117

118
Control the format and verbosity of analysis output.
119

120
```bash { .api }
121
--outputjson
122
# Output results in JSON format instead of text
123

124
--verbose
125
# Emit verbose diagnostics and additional information
126

127
--stats
128
# Print detailed performance statistics
129

130
--dependencies
131
# Emit import dependency information
132

133
--warnings
134
# Use exit code of 1 if warnings are reported (in addition to errors)
135
```
136

137
**Usage Examples:**
138

139
```bash
140
# Get machine-readable JSON output
141
pyright --outputjson > results.json
142

143
# Show detailed performance information
144
pyright --stats --verbose
145

146
# Show import dependencies
147
pyright --dependencies
148

149
# Treat warnings as errors for CI
150
pyright --warnings
151
```
152

153
### Runtime Options
154

155
Configure execution behavior and performance.
156

157
```bash { .api }
158
--threads <optional COUNT>
159
# Use separate threads to parallelize type checking
160
# If COUNT is omitted or "auto", uses CPU core count (minimum 4)
161

162
-w, --watch
163
# Continue to run and watch for file changes
164

165
--help, -h
166
# Show help message and exit
167

168
--version
169
# Print Pyright version and exit
170
```
171

172
**Usage Examples:**
173

174
```bash
175
# Use automatic thread count
176
pyright --threads
177

178
# Use specific thread count
179
pyright --threads 8
180

181
# Watch mode for continuous checking
182
pyright --watch
183

184
# Show version information
185
pyright --version
186
```
187

188
### Deprecated Options
189

190
These options are still supported but deprecated in favor of newer alternatives:
191

192
```bash { .api }
193
--lib
194
# DEPRECATED: Pyright now defaults to using library code to infer types
195

196
--venv-path <DIRECTORY>
197
# DEPRECATED: Use --venvpath instead
198

199
--typeshed-path <DIRECTORY>  
200
# DEPRECATED: Use --typeshedpath instead
201
```
202

203
### Option Compatibility
204

205
Some options are mutually exclusive:
206

207
**--outputjson incompatible with:**
208
- `--stats`, `--verbose`, `--createstub`, `--dependencies`
209

210
**--verifytypes incompatible with:**
211
- `--watch`, `--stats`, `--createstub`, `--dependencies`, `--skipunannotated`, `--threads`
212

213
**--createstub incompatible with:**
214
- `--watch`, `--stats`, `--verifytypes`, `--dependencies`, `--skipunannotated`, `--threads`
215

216
**--threads incompatible with:**
217
- `--watch`, `--stats`, `--dependencies`
218

219
**--pythonpath incompatible with:**
220
- `--venv-path`, `--venvpath`
221

222
### Configuration File Integration
223

224
The CLI respects configuration files in the following order:
225
1. File specified by `--project` option
226
2. `pyrightconfig.json` in current directory
227
3. `pyproject.toml` with `[tool.pyright]` section in current directory
228
4. Search parent directories for configuration files
229

230
### Exit Codes
231

232
```typescript { .api }
233
enum ExitStatus {
234
  NoErrors = 0,              // Successful execution with no errors
235
  ErrorsReported = 1,        // Type errors were found
236
  FatalError = 2,            // Fatal error occurred during execution  
237
  ConfigFileParseError = 3,  // Configuration file parsing failed
238
  ParameterError = 4,        // Invalid command-line parameters
239
}
240
```
241

242
### Multi-threading Behavior
243

244
When using `--threads`:
245
- Analysis is split across multiple worker processes
246
- Each worker analyzes a subset of files
247
- Results are aggregated and reported by the main process
248
- Improves performance on large codebases
249
- Uses file affinity to maximize type cache effectiveness
250

251
### File Input Methods
252

253
```bash
254
# Direct file arguments
255
pyright file1.py file2.py
256

257
# Glob patterns (shell expansion)
258
pyright src/**/*.py
259

260
# Configuration-based discovery
261
pyright --project pyrightconfig.json
262

263
# Stdin file list
264
echo "file1.py file2.py" | pyright -
265
```
266

267
### Environment Variables
268

269
Pyright respects these environment variables:
270
- `PYTHONPATH` - Additional module search paths
271
- Standard Node.js environment variables for the runtime
272

273
### Performance Considerations
274

275
- Use `--threads` for large codebases (>100 files)
276
- Enable `--watch` mode for development workflows
277
- Use `--skipunannotated` to focus on typed code
278
- Configure appropriate `include`/`exclude` patterns in config files
279
- Consider `--level error` to reduce noise in CI environments