0
# Command Line Interface
1

2
Green's command-line interface provides comprehensive test running capabilities with extensive configuration options, multiple output formats, and integration with coverage tools.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The primary function for running Green from the command line, handling argument parsing, configuration merging, and test execution orchestration.
9

10
```python { .api }
11
def main(argv=None, testing=False):
12
    """
13
    Main entry point for Green command-line interface.
14
    
15
    Args:
16
        argv (list, optional): Command-line arguments. If None, uses sys.argv.
17
                              Examples: ['tests/', '--verbose', '2'] 
18
        testing (bool): Enable testing mode which affects some behaviors like
19
                       coverage handling and output formatting. Defaults to False.
20
    
21
    Returns:
22
        int: Exit code - 0 for success (all tests passed), 
23
             non-zero for failure (test failures, errors, or runtime issues)
24
    
25
    Example:
26
        exit_code = main(['tests/', '--verbose', '2', '--run-coverage'])
27
        if exit_code == 0:
28
            print("All tests passed!")
29
    """
30
```
31

32
### Internal Main Implementation
33

34
Internal implementation that handles the core logic of argument processing, configuration setup, and test runner initialization.
35

36
```python { .api }
37
def _main(argv, testing):
38
    """
39
    Internal main implementation handling core CLI logic.
40
    
41
    Args:
42
        argv (list): Parsed command-line arguments
43
        testing (bool): Testing mode flag
44
    
45
    Returns:
46
        int: Exit code
47
    """
48
```
49

50
## Usage Examples
51

52
### Basic Command Line Usage
53

54
```bash
55
# Run all tests in current directory
56
green
57

58
# Run tests in specific directory
59
green tests/
60

61
# Run specific test file
62
green tests/test_module.py
63

64
# Run specific test class
65
green tests.test_module.TestClass
66

67
# Run specific test method
68
green tests.test_module.TestClass.test_method
69
```
70

71
### Verbose Output Options
72

73
```bash
74
# Minimal output (dots only)
75
green -q tests/
76

77
# Standard output 
78
green tests/
79

80
# Verbose output (show test names)
81
green -v tests/
82

83
# More verbose (show docstrings when available)
84
green -vv tests/
85

86
# Most verbose (show file locations)
87
green -vvv tests/
88
```
89

90
### Coverage Integration
91

92
```bash
93
# Run tests with coverage reporting
94
green --run-coverage tests/
95

96
# Coverage with custom config file
97
green --run-coverage --coverage-config-file .coveragerc tests/
98

99
# Coverage with omit patterns
100
green --run-coverage --omit-patterns "*/tests/*,*/venv/*" tests/
101
```
102

103
### Output Formats
104

105
```bash
106
# Generate JUnit XML report
107
green --junit-report results.xml tests/
108

109
# Disable colored output
110
green --no-color tests/
111

112
# Disable Windows-specific formatting
113
green --disable-windows tests/
114
```
115

116
### Parallel Execution Control
117

118
```bash
119
# Use specific number of processes
120
green --processes 4 tests/
121

122
# Use single process (disable parallel execution)
123
green --processes 1 tests/
124

125
# Let Green auto-detect optimal process count (default)
126
green tests/
127
```
128

129
### Configuration Files
130

131
```bash
132
# Use specific config file
133
green --config myconfig.cfg tests/
134

135
# Show location of shell completion file
136
green --completion-file
137

138
# Get shell completions for test targets
139
green --completions tests/test_
140
```
141

142
### Debug and Development
143

144
```bash
145
# Enable debug output
146
green --debug tests/
147

148
# More debug information
149
green --debug --debug tests/
150

151
# Keep temporary files for debugging
152
green --keep-reports tests/
153

154
# Show Green version information
155
green --version
156
```
157

158
## Configuration File Examples
159

160
Green supports configuration files in multiple locations with precedence rules:
161

162
### ~/.green (global configuration)
163
```ini
164
verbose = 2
165
run-coverage = True
166
processes = 4
167
```
168

169
### setup.cfg (project-level)
170
```ini
171
[green]
172
verbose = 1
173
omit-patterns = */tests/*,*/migrations/*
174
junit-report = test-results.xml
175
```
176

177
### .green (directory-level)
178
```ini
179
verbose = 3
180
keep-reports = True
181
debug = True
182
```
183

184
## Shell Integration
185

186
### Bash/Zsh Completion Setup
187

188
```bash
189
# Add to ~/.bashrc or ~/.zshrc
190
which green >& /dev/null && source "$( green --completion-file )"
191
```
192

193
### Environment Variables
194

195
```bash
196
# Specify custom config file location
197
export GREEN_CONFIG=/path/to/custom/green.cfg
198

199
# Then run Green normally
200
green tests/
201
```
202

203
## Exit Codes
204

205
Green returns standard exit codes for integration with CI/CD systems:
206

207
- **0**: All tests passed successfully
208
- **1**: Test failures occurred  
209
- **2**: Test errors occurred
210
- **3**: Configuration or runtime errors
211
- **130**: Interrupted by user (Ctrl+C)
212

213
## Integration Examples
214

215
### CI/CD Pipeline Usage
216

217
```yaml
218
# GitHub Actions example
219
- name: Run tests with Green
220
  run: |
221
    green --junit-report test-results.xml --run-coverage tests/
222
    
223
- name: Upload test results
224
  uses: actions/upload-artifact@v2
225
  with:
226
    name: test-results
227
    path: test-results.xml
228
```
229

230
### Makefile Integration
231

232
```makefile
233
test:
234
	green --verbose 2 tests/
235

236
test-coverage:
237
	green --run-coverage --verbose 2 tests/
238

239
test-ci:
240
	green --junit-report junit.xml --run-coverage --verbose 1 tests/
241
```