0
# LibCST Command-Line Tool
1

2
LibCST provides a powerful command-line interface for parsing, analyzing, and transforming Python code using concrete syntax trees. The CLI tool offers several commands for different operations.
3

4
## Installation and Usage
5

6
The LibCST CLI tool is invoked as a Python module:
7

8
```bash
9
python -m libcst.tool --help
10
```
11

12
## Core Capabilities
13

14
The LibCST command-line tool provides four main commands:
15

16
- **`print`** - Print the LibCST tree representation of Python files
17
- **`codemod`** - Execute code transformations using codemod commands  
18
- **`list`** - List all available codemod commands
19
- **`initialize`** - Initialize a directory with default LibCST configuration
20

21
### Global Options
22

23
All commands support these global options:
24

25
```{ .api }
26
--version           Print current version of LibCST toolset
27
--help, -h         Show help message
28
@file               Read arguments from a file (one per line)
29
```
30

31
## Print Command
32

33
Parse and display the LibCST concrete syntax tree representation of Python code.
34

35
```{ .api }
36
python -m libcst.tool print [OPTIONS] INFILE
37

38
Arguments:
39
  INFILE                    File to print tree for. Use "-" for stdin
40

41
Options:
42
  --show-whitespace        Show whitespace nodes in printed tree
43
  --show-defaults          Show values that are unchanged from the default
44
  --show-syntax            Show values that exist only for syntax (commas, semicolons)
45
  --graphviz               Display the graph in .dot format, compatible with Graphviz
46
  --indent-string STRING   String to use for indenting levels (default: "  ")
47
  -p, --python-version VER Override the version string used for parsing Python files
48
```
49

50
### Print Usage Examples
51

52
Print the CST of a Python file:
53
```bash
54
python -m libcst.tool print my_script.py
55
```
56

57
Parse from stdin and show whitespace nodes:
58
```bash
59
cat my_script.py | python -m libcst.tool print --show-whitespace -
60
```
61

62
Generate Graphviz output for visualization:
63
```bash
64
python -m libcst.tool print --graphviz my_script.py | dot -Tpng -o tree.png
65
```
66

67
Parse with specific Python version:
68
```bash
69
python -m libcst.tool print --python-version 3.9 my_script.py
70
```
71

72
## Codemod Command
73

74
Execute code transformations using LibCST's codemod framework. Codemods are automated code transformation tools that can refactor, update, or modify Python codebases systematically.
75

76
```{ .api }
77
python -m libcst.tool codemod [OPTIONS] COMMAND PATH [PATH ...]
78

79
Arguments:
80
  COMMAND                   Codemod command to execute (e.g., strip_strings_from_types.StripStringsCommand)
81
  PATH                      Path(s) to transform. Can be files, directories, or "-" for stdin
82

83
Options:
84
  -x, --external           Interpret COMMAND as just a module/class specifier
85
  -j, --jobs JOBS          Number of jobs for parallel processing (default: number of cores)
86
  -p, --python-version VER Override Python version for parsing (default: current Python version)
87
  -u, --unified-diff [N]   Output unified diff instead of contents (default context: 5 lines)
88
  --include-generated      Process generated files (normally skipped)
89
  --include-stubs          Process typing stub files (.pyi)
90
  --no-format              Skip formatting with configured formatter
91
  --show-successes         Print successfully transformed files with no warnings
92
  --hide-generated-warnings  Don't print warnings for skipped generated files
93
  --hide-blacklisted-warnings  Don't print warnings for skipped blacklisted files
94
  --hide-progress          Don't show progress indicator
95
```
96

97
### Codemod Usage Examples
98

99
Remove unused imports from a file:
100
```bash
101
python -m libcst.tool codemod remove_unused_imports.RemoveUnusedImportsCommand my_script.py
102
```
103

104
Transform an entire directory with diff output:
105
```bash
106
python -m libcst.tool codemod --unified-diff strip_strings_from_types.StripStringsCommand src/
107
```
108

109
Run codemod from stdin to stdout:
110
```bash
111
cat my_script.py | python -m libcst.tool codemod noop.NOOPCommand -
112
```
113

114
Use external codemod with custom arguments:
115
```bash
116
python -m libcst.tool codemod -x my_custom_codemods.MyTransform --old_name foo --new_name bar src/
117
```
118

119
Process files in parallel:
120
```bash
121
python -m libcst.tool codemod --jobs 8 convert_format_to_fstring.ConvertFormatStringCommand src/
122
```
123

124
## List Command
125

126
Display all available codemod commands and their descriptions.
127

128
```{ .api }
129
python -m libcst.tool list
130
```
131

132
### List Usage Examples
133

134
Show all available codemods:
135
```bash
136
python -m libcst.tool list
137
```
138

139
Example output:
140
```
141
add_trailing_commas.AddTrailingCommasCommand - Add trailing commas to function calls, literals, etc.
142
convert_format_to_fstring.ConvertFormatStringCommand - Convert .format(...) strings to f-strings
143
noop.NOOPCommand - Does absolutely nothing.
144
rename.RenameCommand - Rename all instances of a local or imported object.
145
remove_unused_imports.RemoveUnusedImportsCommand - Remove unused imports from modules.
146
```
147

148
## Initialize Command
149

150
Create a default LibCST configuration file in a directory to configure codemod behavior.
151

152
```{ .api }
153
python -m libcst.tool initialize PATH
154

155
Arguments:
156
  PATH                     Path to initialize with default LibCST configuration
157
```
158

159
### Configuration File
160

161
The `initialize` command creates a `.libcst.codemod.yaml` file with these settings:
162

163
```yaml
164
# String that LibCST should look for in code which indicates that the module is generated code.
165
generated_code_marker: "@generated"
166

167
# Command line and arguments for invoking a code formatter.
168
formatter: ["black", "-"]
169

170
# List of regex patterns which LibCST will evaluate against filenames to determine if the module should be touched.
171
blacklist_patterns: []
172

173
# List of modules that contain codemods inside of them.
174
modules:
175
- libcst.codemod.commands
176

177
# Absolute or relative path of the repository root, used for providing full-repo metadata.
178
repo_root: "."
179
```
180

181
### Initialize Usage Examples
182

183
Initialize current directory:
184
```bash
185
python -m libcst.tool initialize .
186
```
187

188
Initialize a specific project directory:
189
```bash
190
python -m libcst.tool initialize /path/to/my/project
191
```
192

193
## Built-in Codemod Commands
194

195
LibCST includes several built-in codemod commands for common transformations:
196

197
### Text and String Transformations
198
- **`convert_format_to_fstring.ConvertFormatStringCommand`** - Convert `.format()` calls to f-strings
199
- **`convert_percent_format_to_fstring.ConvertPercentFormatToFStringCommand`** - Convert `%` formatting to f-strings
200
- **`unnecessary_format_string.UnnecessaryFormatStringCommand`** - Remove unnecessary f-string formatting
201

202
### Type System Updates
203
- **`convert_type_comments.ConvertTypeComments`** - Convert type comments to annotations
204
- **`convert_union_to_or.ConvertUnionToOrCommand`** - Convert `Union[X, Y]` to `X | Y` (Python 3.10+)
205
- **`strip_strings_from_types.StripStringsCommand`** - Remove string quotes from type annotations
206

207
### Import Management
208
- **`remove_unused_imports.RemoveUnusedImportsCommand`** - Remove imports that are not used
209
- **`ensure_import_present.EnsureImportPresentCommand`** - Add imports if they don't exist
210
- **`rename.RenameCommand`** - Rename symbols and update imports
211

212
### Code Style
213
- **`add_trailing_commas.AddTrailingCommasCommand`** - Add trailing commas to collections
214
- **`convert_namedtuple_to_dataclass.ConvertNamedTupleToDataclassCommand`** - Convert NamedTuple to dataclass
215

216
### Pyre Integration
217
- **`add_pyre_directive.AddPyreDirectiveCommand`** - Add Pyre type checker directives
218
- **`remove_pyre_directive.RemovePyreDirectiveCommand`** - Remove Pyre directives
219
- **`fix_pyre_directives.FixPyreDirectivesCommand`** - Fix malformed Pyre directives
220

221
### Example Codemod Arguments
222

223
Many codemods accept additional arguments. For example:
224

225
```bash
226
# Rename a symbol across the codebase
227
python -m libcst.tool codemod rename.RenameCommand \
228
    --old_name "mymodule.OldClass" \
229
    --new_name "mymodule.NewClass" \
230
    src/
231

232
# Ensure an import is present
233
python -m libcst.tool codemod ensure_import_present.EnsureImportPresentCommand \
234
    --module "typing" \
235
    --entity "List" \
236
    src/
237
```
238

239
## Configuration Management
240

241
### Environment Variables
242

243
- **`LIBCST_TOOL_REQUIRE_CONFIG`** - If set, requires a configuration file to be present
244
- **`LIBCST_TOOL_COMMAND_NAME`** - Override the command name in help text
245

246
### Configuration File Discovery
247

248
LibCST searches for `.libcst.codemod.yaml` configuration files by walking up the directory tree from the current working directory. This allows different parts of a repository to have different codemod configurations.
249

250
### Formatter Integration
251

252
The configuration file specifies a code formatter command that will be automatically applied after codemod transformations. The default is Black, but any formatter that accepts code via stdin and outputs formatted code via stdout can be used.
253

254
## Advanced Usage
255

256
### Custom Codemods
257

258
You can create custom codemods by subclassing from `CodemodCommand`:
259

260
```python
261
from libcst.codemod import CodemodCommand
262
import libcst as cst
263

264
class MyCustomCommand(CodemodCommand):
265
    DESCRIPTION = "My custom transformation"
266
    
267
    def transform_module_impl(self, tree: cst.Module) -> cst.Module:
268
        # Your transformation logic here
269
        return tree
270
```
271

272
### Parallel Processing
273

274
For large codebases, use the `--jobs` option to process files in parallel:
275

276
```bash
277
python -m libcst.tool codemod --jobs 16 my_transform.MyCommand large_codebase/
278
```
279

280
### Integration with CI/CD
281

282
Use `--unified-diff` to generate patches for review:
283

284
```bash
285
python -m libcst.tool codemod --unified-diff my_transform.Command src/ > changes.patch
286
```
287

288
The CLI tool returns appropriate exit codes:
289
- `0` - Success, no failures
290
- `1` - Some files failed to transform
291
- `2` - Interrupted by user (Ctrl+C)
292

293
## Error Handling
294

295
The codemod command provides detailed reporting:
296

297
```
298
Finished codemodding 150 files!
299
 - Transformed 145 files successfully.
300
 - Skipped 3 files.
301
 - Failed to codemod 2 files.
302
 - 5 warnings were generated.
303
```
304

305
Files may be skipped for several reasons:
306
- Generated files (contain the `generated_code_marker` string)
307
- Files matching `blacklist_patterns`
308
- Syntax errors or parse failures
309
- Permission issues
310

311
Use the various `--hide-*` flags to control warning verbosity, and `--show-successes` to see all successfully processed files.