Core CLI Interface

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.

Capabilities

Main Entry Point

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

def main(args: Sequence[str]) -> int:
    """
    Main programmatic entry point for tox.
    
    Args:
        args: Command line arguments (excluding program name)
        
    Returns:
        int: Exit code (0 for success, non-zero for error)
    """

Usage example:

from tox.run import main

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

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

# List environments
result = main(['-l'])

CLI Runner

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.

def run(args: Sequence[str] | None = None) -> None:
    """
    CLI entry point with exception handling and exit code management.
    
    Args:
        args: Command line arguments. If None, uses sys.argv[1:]
        
    Raises:
        SystemExit: Always exits with appropriate code
    """

Usage example:

from tox.run import run

# Run with current command line arguments
run()

# Run with specific arguments
run(['-e', 'py311', '--', 'pytest', '-v'])

State Setup

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

def setup_state(args: Sequence[str]) -> State:
    """
    Setup the state object for a tox run.
    
    Args:
        args: Command line arguments
        
    Returns:
        State: Configured state object ready for execution
    """

Usage example:

from tox.run import setup_state

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

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

# Access environments
envs = state.envs
print(f"Available environments: {list(envs._defined_envs.keys())}")

Version Information

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

__version__: str  # Package version string (generated from VCS during build)

Usage example:

import tox
print(f"Tox version: {tox.__version__}")

Command Line Options

Core Options

Key command line options that control tox behavior:

• -e, --env: Specify environments to run
• -l, --list-envs: List available environments
• -c, --conf: Specify configuration file
• --workdir: Set working directory
• -p, --parallel: Run environments in parallel
• --parallel-no-spinner: Disable progress spinner in parallel mode
• -v, --verbose: Increase verbosity
• -q, --quiet: Decrease verbosity
• --skip-missing-interpreters: Skip missing Python interpreters
• --discover: Discover and print configuration
• --no-provision: Disable automatic provisioning

Advanced Options

• --override: Override configuration values
• --force-dep: Force dependency resolution
• --develop: Install package in development mode
• --installpkg: Install specified package
• --sdistonly: Only create source distribution
• --result-json: Write results to JSON file
• --exit-and-dump-after: Exit and dump after timeout

Exit Codes

Standard exit codes returned by tox:

• 0: Success - all environments passed
• 1: Error - one or more environments failed
• -2: Handled error or keyboard interrupt
• Other non-zero: Unexpected error

Environment Variables

Environment variables that influence tox behavior:

• TOX_WORK_DIR: Override working directory
• TOX_TESTENV_PASSENV: Additional environment variables to pass
• TOX_PARALLEL_NO_SPINNER: Disable parallel spinner
• _TOX_SHOW_THREAD: Debug - show thread information

Error Handling

Key exception types for CLI operations:

class HandledError(RuntimeError):
    """Error that has been handled so no need for stack trace."""

Import from:

from tox.report import HandledError

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