0
# CLI Interface
1

2
Main command-line interface providing the `pip-upgrade` console command with comprehensive options for interactive and automated requirements file upgrading.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The primary entry point for the pip-upgrade command-line tool that orchestrates the complete upgrade workflow.
9

10
```python { .api }
11
def main():
12
    """
13
    Main CLI entrypoint that executes the complete upgrade workflow.
14
    
15
    Workflow:
16
    1. Parse command-line options
17
    2. Check virtual environment status
18
    3. Detect requirements files
19
    4. Parse packages from requirements files
20
    5. Query PyPI for available upgrades
21
    6. Present interactive selection or use pre-selected packages
22
    7. Install packages and update requirements files
23
    
24
    Raises:
25
        KeyboardInterrupt: On user cancellation or validation failures
26
    """
27
```
28

29
### Command-Line Options Parsing
30

31
Parses command-line arguments using docopt and returns a structured options dictionary.
32

33
```python { .api }
34
def get_options():
35
    """
36
    Parse command-line arguments using docopt.
37
    
38
    Returns:
39
        dict: Options dictionary containing all parsed arguments and flags
40
    """
41
```
42

43
## Command-Line Arguments
44

45
### Positional Arguments
46

47
```bash
48
pip-upgrade [<requirements_file>] ...
49
```
50

51
- **requirements_file** (optional, multiple): The requirement file path(s) or wildcard patterns to multiple files. If not provided, the tool will auto-discover requirements files in the current directory.
52

53
### Optional Flags
54

55
```bash
56
--prerelease
57
```
58
Include prerelease versions for upgrade when querying PyPI repositories.
59

60
```bash
61
-p <package> [<package> ...]
62
```
63
Pre-choose which packages to upgrade. Skips the interactive prompt. Special value "all" selects all available upgrades.
64

65
```bash
66
--dry-run
67
```
68
Simulates the upgrade process but does not execute the actual upgrade or file modifications.
69

70
```bash
71
--skip-package-installation
72
```
73
Only upgrade the version numbers in requirements files, don't install the new packages via pip.
74

75
```bash
76
--skip-virtualenv-check
77
```
78
Disable virtualenv check. Allows installing new packages outside of a virtual environment.
79

80
```bash
81
--use-default-index
82
```
83
Skip searching for custom index-url in pip configuration files and use the default PyPI index.
84

85
## Usage Examples
86

87
### Basic Interactive Usage
88

89
```bash
90
# Auto-discover requirements.txt and upgrade interactively
91
pip-upgrade
92

93
# Specify requirements file explicitly
94
pip-upgrade requirements.txt
95

96
# Work with multiple requirements files
97
pip-upgrade requirements/dev.txt requirements/production.txt
98
```
99

100
### Non-Interactive Usage
101

102
```bash
103
# Pre-select specific packages
104
pip-upgrade requirements.txt -p django -p celery
105

106
# Upgrade all available packages
107
pip-upgrade requirements.txt -p all
108
```
109

110
### Dry Run and Simulation
111

112
```bash
113
# Simulate upgrade without making changes
114
pip-upgrade requirements.txt --dry-run
115

116
# Combine with package selection
117
pip-upgrade requirements.txt -p django --dry-run
118
```
119

120
### Environment and Index Options
121

122
```bash
123
# Skip virtualenv validation
124
pip-upgrade requirements.txt --skip-virtualenv-check
125

126
# Only update requirements files, don't install packages
127
pip-upgrade requirements.txt --skip-package-installation
128

129
# Include prerelease versions
130
pip-upgrade requirements.txt --prerelease
131

132
# Use default PyPI instead of custom index
133
pip-upgrade requirements.txt --use-default-index
134
```
135

136
## Error Handling
137

138
The CLI interface handles several types of errors:
139

140
- **KeyboardInterrupt**: User cancellation (Ctrl+C) displays colored "Upgrade interrupted" message
141
- **Virtual environment warnings**: Prompts user when not in a virtual environment unless skipped
142
- **No requirements files**: Displays helpful message when no valid requirements files are found
143
- **No upgrades available**: Shows "All packages are up-to-date" message when appropriate
144
- **Package installation failures**: Continues processing other packages and reports failures
145

146
## Output Format
147

148
The CLI provides colored terminal output using the `colorclass` library:
149

150
- **Yellow**: Informational messages and warnings
151
- **Green**: Success messages and up-to-date packages
152
- **Red**: Error messages and failures
153
- **Cyan**: File names and paths
154
- **Magenta**: Dry-run indicators
155

156
Tables are formatted using the `terminaltables` library for clear presentation of upgrade options.