0
# Core CLI Interface
1

2
Main entry points for command line and programmatic usage of tox. These functions provide the primary interface for executing tox operations, parsing command line arguments, and setting up the execution environment.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The primary programmatic entry point for tox execution. Accepts command line arguments and returns an exit code indicating success or failure.
9

10
```python { .api }
11
def main(args: Sequence[str]) -> int:
12
    """
13
    Main programmatic entry point for tox.
14
    
15
    Args:
16
        args: Command line arguments (excluding program name)
17
        
18
    Returns:
19
        int: Exit code (0 for success, non-zero for error)
20
    """
21
```
22

23
Usage example:
24
```python
25
from tox.run import main
26

27
# Run with specific environments
28
result = main(['-e', 'py311,py312'])
29

30
# Run with configuration file
31
result = main(['-c', 'custom-tox.ini'])
32

33
# List environments
34
result = main(['-l'])
35
```
36

37
### CLI Runner
38

39
High-level CLI entry point that wraps main() with exception handling and system exit behavior. This is the function called by the `tox` command line script.
40

41
```python { .api }
42
def run(args: Sequence[str] | None = None) -> None:
43
    """
44
    CLI entry point with exception handling and exit code management.
45
    
46
    Args:
47
        args: Command line arguments. If None, uses sys.argv[1:]
48
        
49
    Raises:
50
        SystemExit: Always exits with appropriate code
51
    """
52
```
53

54
Usage example:
55
```python
56
from tox.run import run
57

58
# Run with current command line arguments
59
run()
60

61
# Run with specific arguments
62
run(['-e', 'py311', '--', 'pytest', '-v'])
63
```
64

65
### State Setup
66

67
Sets up the runtime state object that coordinates the entire tox execution. This includes parsing CLI arguments, loading configuration, and preparing the execution environment.
68

69
```python { .api }
70
def setup_state(args: Sequence[str]) -> State:
71
    """
72
    Setup the state object for a tox run.
73
    
74
    Args:
75
        args: Command line arguments
76
        
77
    Returns:
78
        State: Configured state object ready for execution
79
    """
80
```
81

82
Usage example:
83
```python
84
from tox.run import setup_state
85

86
# Create state for specific arguments
87
state = setup_state(['-e', 'py311'])
88

89
# Access configuration
90
config = state.conf
91
print(f"Work directory: {config.work_dir}")
92

93
# Access environments
94
envs = state.envs
95
print(f"Available environments: {list(envs._defined_envs.keys())}")
96
```
97

98
### Version Information
99

100
Access to tox version information for programmatic use. The version is generated from VCS tags during build.
101

102
```python { .api }
103
__version__: str  # Package version string (generated from VCS during build)
104
```
105

106
Usage example:
107
```python
108
import tox
109
print(f"Tox version: {tox.__version__}")
110
```
111

112
## Command Line Options
113

114
### Core Options
115

116
Key command line options that control tox behavior:
117

118
- `-e, --env`: Specify environments to run
119
- `-l, --list-envs`: List available environments  
120
- `-c, --conf`: Specify configuration file
121
- `--workdir`: Set working directory
122
- `-p, --parallel`: Run environments in parallel
123
- `--parallel-no-spinner`: Disable progress spinner in parallel mode
124
- `-v, --verbose`: Increase verbosity
125
- `-q, --quiet`: Decrease verbosity
126
- `--skip-missing-interpreters`: Skip missing Python interpreters
127
- `--discover`: Discover and print configuration
128
- `--no-provision`: Disable automatic provisioning
129

130
### Advanced Options
131

132
- `--override`: Override configuration values
133
- `--force-dep`: Force dependency resolution  
134
- `--develop`: Install package in development mode
135
- `--installpkg`: Install specified package
136
- `--sdistonly`: Only create source distribution
137
- `--result-json`: Write results to JSON file
138
- `--exit-and-dump-after`: Exit and dump after timeout
139

140
## Exit Codes
141

142
Standard exit codes returned by tox:
143

144
- `0`: Success - all environments passed
145
- `1`: Error - one or more environments failed
146
- `-2`: Handled error or keyboard interrupt
147
- Other non-zero: Unexpected error
148

149
## Environment Variables
150

151
Environment variables that influence tox behavior:
152

153
- `TOX_WORK_DIR`: Override working directory
154
- `TOX_TESTENV_PASSENV`: Additional environment variables to pass
155
- `TOX_PARALLEL_NO_SPINNER`: Disable parallel spinner
156
- `_TOX_SHOW_THREAD`: Debug - show thread information
157

158
## Error Handling
159

160
Key exception types for CLI operations:
161

162
```python { .api }
163
class HandledError(RuntimeError):
164
    """Error that has been handled so no need for stack trace."""
165
```
166

167
Import from:
168
```python
169
from tox.report import HandledError
170
```
171

172
The `run()` function automatically catches `HandledError` and `KeyboardInterrupt` exceptions and converts them to appropriate exit codes, while other exceptions are re-raised for debugging.