0
# Main Entry Point & Configuration
1

2
Core functionality for running Certbot and managing configuration, including the main CLI entry point, configuration handling, and argument processing.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The primary function for running Certbot programmatically, providing the same functionality as the command-line interface.
9

10
```python { .api }
11
def main(cli_args: Optional[list[str]] = None) -> Optional[Union[str, int]]:
12
    """
13
    Run Certbot with optional command line arguments.
14
    
15
    Args:
16
        cli_args: Command line to Certbot, defaults to sys.argv[1:]
17
    
18
    Returns:
19
        Value for sys.exit about the exit status of Certbot (str, int, or None)
20
    """
21
```
22

23
Usage examples:
24

25
```python
26
from certbot.main import main
27

28
# Run certbot for certificate-only mode
29
result = main(['certonly', '--standalone', '-d', 'example.com'])
30

31
# Run with webroot authenticator
32
result = main(['certonly', '--webroot', '-w', '/var/www/html', '-d', 'example.com'])
33

34
# Run with manual authenticator
35
result = main(['certonly', '--manual', '-d', 'example.com'])
36

37
# Renew certificates
38
result = main(['renew'])
39

40
# Use default command line arguments (sys.argv[1:])
41
result = main()
42
```
43

44
### Configuration Management
45

46
Configuration wrapper that handles command-line arguments, configuration files, and runtime settings.
47

48
```python { .api }
49
class NamespaceConfig:
50
    """
51
    Configuration wrapper around argparse.Namespace.
52
    
53
    Provides dynamic resolution of paths and configuration validation.
54
    """
55
    
56
    def __init__(self, namespace: argparse.Namespace):
57
        """
58
        Initialize configuration with namespace.
59
        
60
        Args:
61
            namespace: Namespace typically produced by ArgumentParser.parse_args()
62
        """
63
    
64
    def set_argument_sources(self, argument_sources: dict[str, ArgumentSource]):
65
        """
66
        Associate the NamespaceConfig with a dictionary describing where each
67
        argument came from for runtime evaluation.
68
        
69
        Args:
70
            argument_sources: Dictionary mapping argument names to their sources
71
        """
72
    
73
    def set_by_user(self, name: str) -> bool:
74
        """
75
        Check if an argument was explicitly set by the user.
76
        
77
        Args:
78
            name: Name of the argument to check
79
            
80
        Returns:
81
            True if set by user, False if using default value
82
        """
83
```
84

85
### Argument Sources
86

87
Enumeration for tracking where configuration arguments originated.
88

89
```python { .api }
90
class ArgumentSource(enum.Enum):
91
    """Enum for describing where a configuration argument was set."""
92
    COMMAND_LINE = enum.auto()  # Argument specified on command line
93
    CONFIG_FILE = enum.auto()   # Argument specified in .ini config file
94
    DEFAULT = enum.auto()       # Argument was not set, using default value
95
    ENV_VAR = enum.auto()       # Argument specified in environment variable
96
    RUNTIME = enum.auto()       # Argument was set at runtime by certbot
97
```
98

99
Usage example:
100

101
```python
102
from certbot import configuration
103
import argparse
104

105
# Create namespace with configuration
106
namespace = argparse.Namespace()
107
namespace.config_dir = '/etc/letsencrypt'
108
namespace.work_dir = '/var/lib/letsencrypt'
109
namespace.logs_dir = '/var/log/letsencrypt'
110

111
# Create configuration wrapper
112
config = configuration.NamespaceConfig(namespace)
113

114
# Set argument sources for tracking
115
sources = {
116
    'config_dir': configuration.ArgumentSource.CONFIG_FILE,
117
    'work_dir': configuration.ArgumentSource.DEFAULT,
118
    'logs_dir': configuration.ArgumentSource.COMMAND_LINE
119
}
120
config.set_argument_sources(sources)
121

122
# Check if argument was set by user
123
if config.set_by_user('config_dir'):
124
    print("Config directory was explicitly set")
125
```
126

127
## Configuration Attributes
128

129
The NamespaceConfig class provides access to various configuration paths and settings:
130

131
### Directory Paths
132

133
```python { .api }
134
# Dynamically resolved using work_dir and relative paths:
135
config.accounts_dir         # Account storage directory
136
config.in_progress_dir      # Temporary operations directory  
137
config.temp_checkpoint_dir  # Temporary checkpoint directory
138

139
# Dynamically resolved using config_dir and relative paths:
140
config.default_archive_dir  # Certificate archive directory
141
config.live_dir            # Live certificate directory
142
config.renewal_configs_dir  # Renewal configuration directory
143

144
# Directly configured paths:
145
config.config_dir          # Main configuration directory
146
config.work_dir           # Working directory for temporary files
147
config.logs_dir           # Log files directory
148
```
149

150
### Other Configuration Options
151

152
```python { .api }
153
config.email              # Contact email address
154
config.agree_tos         # Agree to terms of service
155
config.non_interactive   # Run without user interaction
156
config.staging           # Use staging ACME server
157
config.dry_run          # Perform a test run without changes
158
config.force_renewal    # Force certificate renewal
159
```