0
# AWS CLI
1

2
AWS CLI (awscli) is a unified command line interface for Amazon Web Services that provides comprehensive programmatic access to AWS services. Beyond its primary role as a command-line tool, it offers a rich Python API for building custom automation, creating CLI extensions, and integrating AWS functionality into applications.
3

4
## Package Information
5

6
- **Package Name**: awscli
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install awscli`
10
- **Python Requirements**: Python 3.9+ (3.9, 3.10, 3.11, 3.12, 3.13)
11

12
## Core Imports
13

14
```python
15
import awscli
16
from awscli.clidriver import main, create_clidriver
17
```
18

19
Common programmatic usage:
20

21
```python
22
from awscli.clidriver import CLIDriver, create_clidriver
23
from awscli.commands import CLICommand
24
from awscli.customizations.commands import BasicCommand
25
```
26

27
## Basic Usage
28

29
### Command Line Execution
30
```python
31
from awscli.clidriver import main
32
import sys
33

34
# Execute AWS CLI commands programmatically
35
exit_code = main(['s3', 'ls'])
36
sys.exit(exit_code)
37
```
38

39
### Programmatic CLI Driver
40
```python
41
from awscli.clidriver import create_clidriver
42

43
# Create a CLI driver instance for more control
44
driver = create_clidriver()
45
exit_code = driver.main(['ec2', 'describe-instances', '--region', 'us-east-1'])
46
print(f"Command completed with exit code: {exit_code}")
47
```
48

49
### Custom Command Development
50
```python
51
from awscli.customizations.commands import BasicCommand
52

53
class MyCustomCommand(BasicCommand):
54
    NAME = 'my-custom-command'
55
    DESCRIPTION = 'A custom AWS CLI command'
56
    
57
    def _run_main(self, parsed_args, parsed_globals):
58
        print("Executing custom command")
59
        return 0
60
```
61

62
## Architecture
63

64
The AWS CLI is built on a layered architecture that enables extensive customization:
65

66
- **CLI Driver**: Core execution engine that processes commands and manages session state
67
- **Command System**: Hierarchical command structure supporting services, operations, and custom commands  
68
- **Argument Processing**: Flexible argument parsing, validation, and transformation system
69
- **Plugin Architecture**: Event-driven plugin system for extending functionality
70
- **Output Formatting**: Multiple output formats (JSON, table, text, YAML) with customizable formatters
71
- **Session Management**: Integration with botocore for AWS service communication and credential management
72

73
This design enables AWS CLI to serve as both a powerful command-line tool and a foundation for building AWS-powered applications and automation tools.
74

75
## Capabilities
76

77
### Core CLI Driver
78

79
The foundational CLI execution system that provides programmatic access to AWS CLI functionality, including session management, command routing, and plugin integration.
80

81
```python { .api }
82
def main() -> int: ...
83
def create_clidriver() -> CLIDriver: ...
84

85
class CLIDriver:
86
    def __init__(self, session=None): ...
87
    def main(self, args=None) -> int: ...
88
    def create_help_command(self): ...
89
```
90

91
[Core CLI Driver](./core-driver.md)
92

93
### Command System
94

95
Comprehensive command framework for creating and executing AWS service operations and custom commands, with support for hierarchical command structures and argument processing.
96

97
```python { .api }
98
class CLICommand:
99
    name: str
100
    lineage: list
101
    lineage_names: list
102
    arg_table: dict
103
    
104
    def __call__(self, args, parsed_globals): ...
105
    def create_help_command(self): ...
106

107
class ServiceCommand(CLICommand):
108
    def __init__(self, cli_name, session, service_name=None): ...
109

110
class ServiceOperation:
111
    def __init__(self, name, parent_name, operation_caller, operation_model, session): ...
112
```
113

114
[Command System](./command-system.md)
115

116
### Argument Processing
117

118
Advanced argument parsing, validation, and transformation system supporting complex AWS parameter structures, shorthand syntax, and file-based parameter input.
119

120
```python { .api }
121
class BaseCLIArgument:
122
    def __init__(self, name): ...
123
    def add_to_arg_table(self): ...
124
    def add_to_parser(self): ...
125
    def add_to_params(self): ...
126

127
class CustomArgument(BaseCLIArgument):
128
    def __init__(self, name, help_text='', dest=None, default=None, 
129
                 action=None, required=None, choices=None, nargs=None,
130
                 cli_type_name=None, group_name=None, positional_arg=False,
131
                 no_paramfile=False, argument_model=None, synopsis='', const=None): ...
132

133
def unpack_argument(session, service_name, operation_name, cli_argument, value): ...
134
```
135

136
[Argument Processing](./argument-processing.md)
137

138
### Custom Commands Framework
139

140
Extensible framework for creating custom CLI commands with built-in support for argument handling, help generation, and integration with the AWS CLI command hierarchy.
141

142
```python { .api }
143
class BasicCommand(CLICommand):
144
    NAME: str
145
    DESCRIPTION: str
146
    SYNOPSIS: str
147
    EXAMPLES: str
148
    ARG_TABLE: dict
149
    SUBCOMMANDS: dict
150
    
151
    FROM_FILE: type
152

153
class _FromFile:
154
    def __init__(self, *paths, **kwargs): ...
155
```
156

157
[Custom Commands](./custom-commands.md)
158

159
### Plugin System
160

161
Event-driven plugin architecture for extending AWS CLI functionality with custom handlers, commands, and integrations.
162

163
```python { .api }
164
def load_plugins(plugin_mapping, event_hooks=None, include_builtins=True): ...
165

166
BUILTIN_PLUGINS: dict
167
```
168

169
[Plugin System](./plugin-system.md)
170

171
### Output Formatting
172

173
Flexible output formatting system supporting multiple formats (JSON, table, text, YAML) with customizable formatters and styling options.
174

175
```python { .api }
176
def get_formatter(output_format, args): ...
177
def is_response_paginated(response) -> bool: ...
178

179
class Formatter:
180
    def __init__(self, args): ...
181

182
class TableFormatter:
183
    def __init__(self, args): ...
184

185
class MultiTable: ...
186
```
187

188
[Output Formatting](./output-formatting.md)
189

190
### Utilities and Helpers
191

192
Comprehensive utility functions for AWS CLI operations, including JSON handling, exception management, client creation, and compatibility helpers.
193

194
```python { .api }
195
def split_on_commas(value) -> list: ...
196
def emit_top_level_args_parsed_event(session, args): ...
197
def write_exception(ex, outfile): ...
198
def create_nested_client(session, service_name, region_name=None, 
199
                        endpoint_url=None, verify=None): ...
200
def json_encoder(obj): ...
201
```
202

203
[Utilities](./utilities.md)
204

205
### Testing Framework
206

207
Extensive testing utilities for developing and validating AWS CLI commands, including test base classes, output capture, and AWS service mocking.
208

209
```python { .api }
210
class BaseCLIDriverTest(unittest.TestCase): ...
211
class BaseAWSCommandParamsTest(unittest.TestCase): ...
212
class BaseS3CLICommand(unittest.TestCase): ...
213

214
def create_clidriver(): ...
215
def aws(*args): ...
216
def capture_output(): ...
217
```
218

219
[Testing Framework](./testing-framework.md)
220

221
### Help System
222

223
Comprehensive help system providing contextual documentation for AWS CLI commands, services, and operations with platform-specific rendering and interactive navigation.
224

225
```python { .api }
226
class HelpCommand:
227
    def __init__(self, session, command_table, arg_table, name, event_class=None): ...
228
    def create_help_command(self): ...
229
    def __call__(self, args, parsed_globals): ...
230

231
class ProviderHelpCommand(HelpCommand): ...
232
class ServiceHelpCommand(HelpCommand): ...  
233
class OperationHelpCommand(HelpCommand): ...
234

235
def get_renderer(): ...
236
class PosixHelpRenderer: ...
237
class WindowsHelpRenderer: ...
238
```
239

240
[Help System](./help-system.md)
241

242
### Error Handling
243

244
Structured exception handling system for AWS CLI operations, providing comprehensive error processing, HTTP error handling, and user-friendly error reporting.
245

246
```python { .api }
247
class UnknownArgumentError(Exception): ...
248
class ParamError(Exception): ...
249
class ParamSyntaxError(ParamError): ...
250
class ParamUnknownKeyError(ParamError): ...
251

252
class ErrorHandler:
253
    def __call__(self, parsed, **kwargs): ...
254

255
class ClientError(Exception): ...
256
class ServerError(Exception): ...
257

258
def write_exception(ex, outfile): ...
259
```
260

261
[Error Handling](./error-handling.md)
262

263
## Types
264

265
### Core Types
266

267
```python { .api }
268
# Package constants
269
__version__: str
270
EnvironmentVariables: dict
271
SCALAR_TYPES: set[str]
272
COMPLEX_TYPES: set[str]
273

274
# Core type aliases
275
ArgumentTable = dict[str, BaseCLIArgument]
276
CommandTable = dict[str, CLICommand]
277
ParsedArgs = argparse.Namespace
278
ParsedGlobals = argparse.Namespace
279

280
# Exception types
281
class UnknownArgumentError(Exception): ...
282
class ParamError(Exception): ...
283
class ParamSyntaxError(Exception): ...
284
class ParamUnknownKeyError(Exception): ...
285
class ClientError(Exception): ...
286
class ServerError(Exception): ...
287
class ExecutableNotFoundError(Exception): ...
288
```