0
# Core CLI Driver
1

2
The foundational CLI execution system that provides programmatic access to AWS CLI functionality. The CLI driver manages session state, command routing, plugin loading, and serves as the primary entry point for executing AWS CLI operations programmatically.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The primary function for executing AWS CLI commands programmatically, identical to running the `aws` command from the command line.
9

10
```python { .api }
11
def main() -> int:
12
    """
13
    Main CLI entry point that creates a driver and executes commands.
14
    
15
    Returns:
16
        int: Exit code (0 for success, non-zero for failure)
17
    """
18
```
19

20
**Usage Example:**
21
```python
22
from awscli.clidriver import main
23
import sys
24

25
# Execute AWS CLI command programmatically
26
exit_code = main(['s3', 'ls'])
27
if exit_code == 0:
28
    print("Command succeeded")
29
else:
30
    print("Command failed")
31
    sys.exit(exit_code)
32
```
33

34
### CLI Driver Factory
35

36
Factory function to create a CLI driver instance with proper session initialization and plugin loading.
37

38
```python { .api }
39
def create_clidriver() -> CLIDriver:
40
    """
41
    Create and configure a CLI driver instance.
42
    
43
    Returns:
44
        CLIDriver: Configured CLI driver ready for command execution
45
    """
46
```
47

48
### CLI Driver Class
49

50
The main CLI driver class that orchestrates command execution, argument parsing, and output formatting.
51

52
```python { .api }
53
class CLIDriver:
54
    def __init__(self, session=None):
55
        """
56
        Initialize CLI driver with optional botocore session.
57
        
58
        Parameters:
59
            session: botocore.session.Session, optional AWS session
60
        """
61
    
62
    def main(self, args=None) -> int:
63
        """
64
        Execute CLI command with given arguments.
65
        
66
        Parameters:
67
            args: list[str], optional command arguments (defaults to sys.argv[1:])
68
            
69
        Returns:
70
            int: Exit code (0 for success, non-zero for failure)
71
        """
72
    
73
    def create_help_command(self):
74
        """
75
        Create help command instance for the CLI.
76
        
77
        Returns:
78
            Help command instance
79
        """
80
    
81
    @property
82
    def session(self):
83
        """Botocore session instance for AWS service communication."""
84
```
85

86
**Usage Example:**
87
```python
88
from awscli.clidriver import create_clidriver
89

90
# Create driver with default session
91
driver = create_clidriver()
92

93
# Execute multiple commands
94
commands = [
95
    ['s3', 'ls'],
96
    ['ec2', 'describe-instances', '--region', 'us-east-1'],
97
    ['iam', 'list-users']
98
]
99

100
for cmd in commands:
101
    exit_code = driver.main(cmd)
102
    print(f"Command {' '.join(cmd)} completed with exit code: {exit_code}")
103
```
104

105
### Service Command
106

107
Represents AWS service commands (e.g., s3, ec2, iam) in the command hierarchy.
108

109
```python { .api }
110
class ServiceCommand(CLICommand):
111
    def __init__(self, cli_name, session, service_name=None):
112
        """
113
        Initialize service command.
114
        
115
        Parameters:
116
            cli_name: str, CLI name for the service
117
            session: botocore.session.Session, AWS session
118
            service_name: str, optional service name (defaults to cli_name)
119
        """
120
    
121
    @property
122
    def name(self) -> str:
123
        """Service command name."""
124
    
125
    @property
126
    def service_model(self):
127
        """Botocore service model for the service."""
128
    
129
    @property
130
    def lineage(self) -> list:
131
        """Command hierarchy lineage."""
132
    
133
    def create_help_command(self):
134
        """Create service-level help command."""
135
```
136

137
### Service Operation
138

139
Represents individual operations within AWS services (e.g., s3 cp, ec2 describe-instances).
140

141
```python { .api }
142
class ServiceOperation:
143
    def __init__(self, name, parent_name, operation_caller, operation_model, session):
144
        """
145
        Initialize service operation.
146
        
147
        Parameters:
148
            name: str, operation name
149
            parent_name: str, parent service name
150
            operation_caller: CLIOperationCaller, operation executor
151
            operation_model: botocore operation model
152
            session: botocore.session.Session, AWS session
153
        """
154
    
155
    @property
156
    def name(self) -> str:
157
        """Operation name."""
158
    
159
    @property
160
    def lineage(self) -> list:
161
        """Command hierarchy lineage."""
162
    
163
    @property
164
    def lineage_names(self) -> list[str]:
165
        """List of command names in hierarchy."""
166
    
167
    @property
168
    def arg_table(self) -> dict:
169
        """Argument table for operation parameters."""
170
    
171
    def create_help_command(self):
172
        """Create operation-level help command."""
173
```
174

175
### Operation Caller
176

177
Handles the execution of AWS service operations and response formatting.
178

179
```python { .api }
180
class CLIOperationCaller:
181
    def __init__(self, session):
182
        """
183
        Initialize operation caller with AWS session.
184
        
185
        Parameters:
186
            session: botocore.session.Session, AWS session
187
        """
188
    
189
    def invoke(self, service_name, operation_name, parameters, parsed_globals):
190
        """
191
        Execute AWS service operation.
192
        
193
        Parameters:
194
            service_name: str, AWS service name
195
            operation_name: str, operation name
196
            parameters: dict, operation parameters
197
            parsed_globals: parsed global arguments
198
            
199
        Returns:
200
            Operation response
201
        """
202
```
203

204
**Usage Example:**
205
```python
206
import botocore.session
207
from awscli.clidriver import CLIOperationCaller
208

209
# Create session and operation caller
210
session = botocore.session.Session()
211
caller = CLIOperationCaller(session)
212

213
# Execute operation directly
214
response = caller.invoke(
215
    service_name='s3',
216
    operation_name='list-objects-v2',
217
    parameters={'Bucket': 'my-bucket'},
218
    parsed_globals={}
219
)
220
```
221

222
## Integration Patterns
223

224
### Custom Driver Integration
225

226
```python
227
import botocore.session
228
from awscli.clidriver import CLIDriver
229

230
# Create custom session with specific configuration
231
session = botocore.session.Session()
232
session.set_config_variable('region', 'us-west-2')
233
session.set_config_variable('output', 'json')
234

235
# Create driver with custom session
236
driver = CLIDriver(session=session)
237

238
# Execute commands with custom configuration
239
exit_code = driver.main(['s3', 'ls'])
240
```
241

242
### Error Handling
243

244
```python
245
from awscli.clidriver import main
246
from botocore.exceptions import NoCredentialsError, NoRegionError
247

248
try:
249
    exit_code = main(['s3', 'ls'])
250
    if exit_code != 0:
251
        print("Command failed with non-zero exit code")
252
except NoCredentialsError:
253
    print("AWS credentials not configured")
254
except NoRegionError:
255
    print("AWS region not configured")
256
except Exception as e:
257
    print(f"Unexpected error: {e}")
258
```