0
# Command Line Interface
1

2
The `pygmentize` command-line tool provides syntax highlighting functionality directly from the terminal, supporting all lexers, formatters, and styles available in Pygments.
3

4
## Capabilities
5

6
### Basic Command Structure
7

8
```bash { .api }
9
pygmentize [options] [file]
10
```
11

12
The main entry point for command-line syntax highlighting.
13

14
### Core Options
15

16
```bash { .api }
17
# Specify lexer (language)
18
pygmentize -l <lexer> [file]
19
pygmentize --lexer=<lexer> [file]
20

21
# Specify formatter (output format)  
22
pygmentize -f <formatter> [file]
23
pygmentize --formatter=<formatter> [file]
24

25
# Specify style (color scheme)
26
pygmentize -S <style> -f <formatter>
27
pygmentize --style=<style> --formatter=<formatter>
28

29
# Guess lexer from content
30
pygmentize -g [file]
31
pygmentize --guess-lexer [file]
32

33
# Output to file
34
pygmentize -o <output> [options] [file]
35
pygmentize --outfile=<output> [options] [file]
36
```
37

38
### Option Passing
39

40
```bash { .api }
41
# Pass options to lexer
42
pygmentize -l python -P stripall=true -P tabsize=4 file.py
43

44
# Pass options to formatter
45
pygmentize -f html -O linenos=true -O cssclass=highlight file.py
46

47
# Multiple options
48
pygmentize -l python -f html -O linenos=true,cssclass=code file.py
49
```
50

51
### Information Commands
52

53
```bash { .api }
54
# List all lexers
55
pygmentize -L lexers
56

57
# List all formatters
58
pygmentize -L formatters
59

60
# List all styles
61
pygmentize -L styles
62

63
# List all filters
64
pygmentize -L filters
65

66
# Get help for specific component
67
pygmentize -H lexer python
68
pygmentize -H formatter html
69
pygmentize -H filter codetagfilter
70
```
71

72
## Usage Examples
73

74
### Basic Highlighting
75

76
```bash
77
# Highlight Python file to HTML
78
pygmentize -l python -f html script.py
79

80
# Highlight with guessed lexer
81
pygmentize -g -f html script.py
82

83
# Highlight to terminal with colors
84
pygmentize -l python -f terminal script.py
85
```
86

87
### Output to Files
88

89
```bash
90
# Save HTML output
91
pygmentize -l python -f html -o output.html script.py
92

93
# Generate LaTeX
94
pygmentize -l python -f latex -o document.tex script.py
95

96
# Create PNG image (requires Pillow)
97
pygmentize -l python -f png -o code.png script.py
98
```
99

100
### Style Customization
101

102
```bash
103
# Use different color schemes
104
pygmentize -l python -f html -S monokai script.py
105
pygmentize -l python -f html -S github script.py  
106
pygmentize -l python -f html -S vim script.py
107

108
# Terminal with color schemes
109
pygmentize -l python -f terminal256 -S monokai script.py
110
```
111

112
### Advanced Options
113

114
```bash
115
# HTML with line numbers and custom CSS class
116
pygmentize -l python -f html -O linenos=true,cssclass=highlight script.py
117

118
# HTML with inline styles (no external CSS)
119
pygmentize -l python -f html -O noclasses=true script.py
120

121
# Full HTML document
122
pygmentize -l python -f html -O full=true,title="My Code" script.py
123

124
# LaTeX with line numbers
125
pygmentize -l python -f latex -O linenos=true script.py
126
```
127

128
### Filter Application
129

130
```bash
131
# Apply filters
132
pygmentize -l python -f html -F codetagfilter script.py
133
pygmentize -l python -f html -F keywordcase:case=upper script.py
134

135
# Multiple filters
136
pygmentize -l python -f html -F codetagfilter -F visiblewhitespace script.py
137
```
138

139
### Stdin/Stdout Usage
140

141
```bash
142
# Read from stdin
143
echo "print('Hello')" | pygmentize -l python -f html
144

145
# Pipe output
146
pygmentize -l python -f html script.py | less
147

148
# Chain with other tools
149
cat script.py | pygmentize -g -f terminal | grep -A5 -B5 "function"
150
```
151

152
## Output Formats
153

154
### HTML Output
155

156
```bash
157
# Basic HTML
158
pygmentize -l python -f html script.py
159

160
# HTML with options
161
pygmentize -l python -f html -O linenos=true,cssclass=code,title="Code" script.py
162
```
163

164
### Terminal Output
165

166
```bash
167
# Basic terminal colors (16 colors)
168
pygmentize -l python -f terminal script.py
169

170
# 256-color terminal
171
pygmentize -l python -f terminal256 script.py
172

173
# True color terminal (24-bit)
174
pygmentize -l python -f terminal16m script.py
175
```
176

177
### Document Formats
178

179
```bash
180
# LaTeX
181
pygmentize -l python -f latex script.py
182

183
# RTF (Rich Text Format)
184
pygmentize -l python -f rtf script.py
185

186
# SVG vector graphics
187
pygmentize -l python -f svg script.py
188
```
189

190
### Image Formats
191

192
```bash
193
# PNG image (requires Pillow)
194
pygmentize -l python -f png -O font_size=14 script.py
195

196
# JPEG image
197
pygmentize -l python -f jpeg script.py
198

199
# GIF image
200
pygmentize -l python -f gif script.py
201
```
202

203
## Configuration
204

205
### Style Generation
206

207
Generate CSS for HTML output:
208

209
```bash
210
# Generate CSS for a style
211
pygmentize -S default -f html > style.css
212
pygmentize -S monokai -f html > dark.css
213

214
# Use generated CSS with HTML
215
pygmentize -l python -f html -O cssfile=style.css script.py
216
```
217

218
### Batch Processing
219

220
```bash
221
# Process multiple files
222
for file in *.py; do
223
    pygmentize -l python -f html -o "${file%.py}.html" "$file"
224
done
225

226
# Using find
227
find . -name "*.py" -exec pygmentize -l python -f html -o {}.html {} \;
228
```
229

230
### Integration Examples
231

232
```bash
233
# Git diff with syntax highlighting
234
git show | pygmentize -l diff -f terminal
235

236
# Highlight code in README
237
pygmentize -l python -f html code_sample.py > code.html
238

239
# Generate documentation
240
pygmentize -l python -f latex -O full=true,title="API Reference" api.py > api.tex
241
```
242

243
## Error Handling
244

245
Common command-line errors:
246

247
```bash
248
# Unknown lexer
249
pygmentize -l nonexistent file.py
250
# Error: no lexer for alias 'nonexistent' found
251

252
# Unknown formatter  
253
pygmentize -l python -f badformat file.py
254
# Error: no formatter found for name 'badformat'
255

256
# File not found
257
pygmentize -l python nonexistent.py
258
# Error: cannot read file
259

260
# Invalid options
261
pygmentize -l python -f html -O badoption=true file.py
262
# Error: unknown option 'badoption'
263
```
264

265
## Environment Variables
266

267
```bash
268
# Default options
269
export PYGMENTIZE_STYLE=monokai
270
export PYGMENTIZE_FORMATTER=terminal256
271

272
# Use in scripts
273
pygmentize -l python file.py  # Uses environment defaults
274
```
275

276
## Integration with Other Tools
277

278
### Vim Integration
279

280
```vim
281
# In .vimrc
282
command! -range=% Highlight :<line1>,<line2>w !pygmentize -l python -f html
283
```
284

285
### Less Integration
286

287
```bash
288
# Use as LESSOPEN processor
289
export LESSOPEN="| pygmentize -g %s"
290
less script.py  # Automatically highlighted
291
```
292

293
### Shell Functions
294

295
```bash
296
# Bash function for quick highlighting
297
highlight() {
298
    pygmentize -g -f terminal256 "$1" | less -R
299
}
300

301
# Usage: highlight script.py
302
```