0
# Command Line Interface
1

2
Refurb's primary interface for code analysis with comprehensive options for configuration, error filtering, output formatting, and integration with development workflows.
3

4
## Capabilities
5

6
### Main Entry Points
7

8
Core functions that provide the CLI functionality and entry points for refurb.
9

10
```python { .api }
11
def main(args: list[str]) -> int:
12
    """
13
    Main CLI entry point that processes command line arguments and executes refurb analysis.
14
    
15
    Parameters:
16
    - args: List of command line arguments
17
    
18
    Returns:
19
    Exit code (0 for success, 1 for errors or findings)
20
    """
21

22
def usage() -> None:
23
    """
24
    Display comprehensive help information including all command line options,
25
    subcommands, and usage examples.
26
    """
27

28
def version() -> str:
29
    """
30
    Get version information for both refurb and the underlying mypy dependency.
31
    
32
    Returns:
33
    Formatted version string containing refurb and mypy versions
34
    """
35

36
def explain(settings: Settings) -> str:
37
    """
38
    Generate detailed explanation for a specific error code.
39
    
40
    Parameters:
41
    - settings: Settings object with explain field set to target ErrorCode
42
    
43
    Returns:
44
    Formatted explanation string with error description, examples, and filename
45
    """
46
```
47

48
### Command Line Options
49

50
Refurb supports extensive command line configuration:
51

52
**Analysis Control:**
53
- `--ignore err`: Ignore specific error codes (can be repeated)
54
- `--enable err`: Enable checks disabled by default (can be repeated) 
55
- `--disable err`: Disable checks enabled by default (can be repeated)
56
- `--enable-all`: Enable all available checks
57
- `--disable-all`: Disable all checks by default
58
- `--load module`: Add module to check search paths (can be repeated)
59

60
**Output Formatting:**
61
- `--format format`: Output format ("text" or "github")
62
- `--sort sort`: Sort order ("filename" or "error")
63
- `--quiet`: Suppress default explanation suggestions
64
- `--verbose`: Increase verbosity
65
- `--debug`: Print AST representation of analyzed files
66

67
**Configuration:**
68
- `--config-file file`: Load specified config file instead of default
69
- `--python-version x.y`: Target Python version for analysis
70
- `--timing-stats file`: Export timing information as JSON
71

72
**Information Commands:**
73
- `--help`, `-h`: Display help menu
74
- `--version`: Print version information
75
- `--explain err`: Print explanation for specific error code
76

77
### Subcommands
78

79
```bash
80
# Generate boilerplate code for new checks
81
refurb gen
82
```
83

84
### Usage Patterns
85

86
```bash
87
# Basic analysis
88
refurb src/
89

90
# Multiple files and directories  
91
refurb file1.py src/ tests/
92

93
# Ignore specific errors
94
refurb --ignore FURB105,FURB123 src/
95

96
# Enable additional checks
97
refurb --enable FURB999 --enable-all src/
98

99
# Custom formatting for CI
100
refurb --format github --quiet src/
101

102
# Load custom checks
103
refurb --load ./my_checks --load ./more_checks src/
104

105
# Target specific Python version
106
refurb --python-version 3.11 src/
107

108
# Pass additional arguments to mypy
109
refurb src/ -- --strict --disallow-untyped-defs
110

111
# Get detailed error explanation
112
refurb --explain FURB105
113

114
# Performance analysis
115
refurb --timing-stats timing.json src/
116
```
117

118
### Integration Examples
119

120
```bash
121
# Pre-commit hook
122
refurb --format github --quiet
123

124
# GitHub Actions
125
refurb --format github src/
126

127
# CI pipeline with custom config
128
refurb --config-file .refurb.toml --format github src/
129
```