AWS cli documentation change
Summary
Updated AWS CLI version references, removed sections on API Versions and AWS STS, added pager configuration details, plugins section, cli_binary_format documentation, OS-specific encoding settings, and retry configuration changes. Removed cli_follow_urlparam and updated timestamp format.
Security assessment
The addition of cli_binary_format documentation explains secure handling of binary data (base64 vs. raw-in-base64-out), which helps prevent data corruption or injection risks. The removal of cli_follow_urlparam (which allowed fetching URL parameters) could mitigate potential SSRF vulnerabilities, but the diff provides no explicit security context for this removal. Other changes are routine updates or feature documentation.
Diff
diff --git a/cli/latest/topic/config-vars.md b/cli/latest/topic/config-vars.md index 9fc854e7f..7f77aa323 100644 --- a//cli/latest/topic/config-vars.md +++ b//cli/latest/topic/config-vars.md @@ -15 +15 @@ - * [AWS CLI 1.40.40 Command Reference](../index.html) » + * [AWS CLI 2.27.42 Command Reference](../index.html) » @@ -42,2 +41,0 @@ - * API Versions - * AWS STS @@ -47,0 +46,5 @@ + * Pager + * Configuring pager + * Examples + * Pager settings + * Plugins @@ -64,6 +66,0 @@ First time using the AWS CLI? See the [User Guide](https://docs.aws.amazon.com/c -### Note: - -You are viewing the documentation for an older major version of the AWS CLI (version 1). - -AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click [here](https://awscli.amazonaws.com/v2/documentation/api/latest/topic/config-vars.html). For more information see the AWS CLI version 2 [installation instructions](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) and [migration guide](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html). - @@ -131 +127,0 @@ cli_timestamp_format | N/A | cli_timestamp_format | N/A | Output format of times -cli_follow_urlparam | N/A | cli_follow_urlparam | N/A | Fetch URL url parameters @@ -136,0 +133 @@ retry_mode | N/A | retry_mode | AWS_RETRY_MODE | Type of retries performed +cli_pager | –no-cli-pager | cli_pager | AWS_PAGER | Redirect/Disable output to pager @@ -150 +147 @@ The valid values of the `output` configuration variable are: - * none - Display the timestamp exactly as received from the HTTP response. + * wire - Display the timestamp exactly as received from the HTTP response. @@ -155 +152,4 @@ The valid values of the `output` configuration variable are: -`cli_follow_urlparam` controls whether or not the CLI will attempt to follow URL links in parameters that start with either prefix `https://` or `http://`. The valid values of the `cli_follow_urlparam` configuration variable are: +`cli_binary_format` controls the format of binary values in input and output. The valid values of the `cli_binary_format` configuration variable are: + + * base64 - Binary values are provided as Base64 encoded strings. The default. + * raw-in-base64-out - Binary values are provided are treated literally. Consistent with AWS CLI V1. @@ -157,2 +156,0 @@ The valid values of the `output` configuration variable are: - * true - This is the default value. With this configured the CLI will follow any string parameters that start with `https://` or `http://` will be fetched, and the downloaded content will be used as the parameter instead. - * false - The CLI will not treat strings prefixed with `https://` or `http://` any differently than normal string parameters. @@ -160,0 +159,3 @@ The valid values of the `output` configuration variable are: +When providing contents from a file that map to a binary blob `fileb://` will always be treated as binary and use the file contents directly regardless of the `cli_binary_format` setting. When using `file://` the file contents will need to properly formatted for the configured `cli_binary_format`. + +The default value is `iso8601`. @@ -348 +349 @@ Example configuration with parameters: -### API Versions¶ +### Retry Configuration¶ @@ -350 +351 @@ Example configuration with parameters: -The API version to use for a service can be set using the `api_versions` key. To specify an API version, set the API version to the name of the service as a sub value for `api_versions`. +These configuration variables control how the AWS CLI retries requests. @@ -352 +353,3 @@ The API version to use for a service can be set using the `api_versions` key. To -Example configuration: +`max_attempts` + An integer representing the maximum number attempts that will be made for a single request, including the initial attempt. For example, setting this value to 5 will result in a request being retried up to 4 times. If not provided, the number of retries will default to whatever is modeled, which is typically 5 total attempts in the `legacy` retry mode, and 3 in the `standard` and `adaptive` retry modes. +`retry_mode` @@ -355,6 +358 @@ Example configuration: - [profile development] - aws_access_key_id=foo - aws_secret_access_key=bar - api_versions = - ec2 = 2015-03-01 - cloudfront = 2015-09-17 +A string representing the type of retries the AWS CLI will perform. Value values are: @@ -361,0 +360,3 @@ Example configuration: +> * `standard` \- A standardized set of retry rules across the AWS SDKs. This includes a standard set of errors that are retried as well as support for retry quotas, which limit the number of unsuccessful retries an SDK can make. This mode will default the maximum number of attempts to 3 unless a `max_attempts` is explicitly provided. +> * `adaptive` \- An experimental retry mode that includes all the functionality of `standard` mode along with automatic client side throttling. This is a provisional mode that may change behavior in the future. +> @@ -363 +363,0 @@ Example configuration: -By setting an API version for a service, it ensures that the interface for that service’s commands is representative of the specified API version. @@ -365 +365 @@ By setting an API version for a service, it ensures that the interface for that -In the example configuration, the `ec2` CLI commands will be representative of Amazon EC2’s `2015-03-01` API version and the `cloudfront` CLI commands will be representative of Amazon CloudFront’s `2015-09-17` API version. +### Amazon S3¶ @@ -367 +367 @@ In the example configuration, the `ec2` CLI commands will be representative of A -### AWS STS¶ +There are a number of configuration variables specific to the S3 commands. See [AWS CLI S3 Configuration](s3-config.html) (`aws help topics s3-config`) for more details. @@ -369 +369 @@ In the example configuration, the `ec2` CLI commands will be representative of A -To set STS endpoint resolution logic, use the `AWS_STS_REGIONAL_ENDPOINTS` environment variable or `sts_regional_endpoints` configuration file option. By default, this configuration option is set to `legacy`. Valid values are: +## OS Specific Configuration¶ @@ -371 +371 @@ To set STS endpoint resolution logic, use the `AWS_STS_REGIONAL_ENDPOINTS` envir - * `regional` +### Locale¶ @@ -372,0 +373 @@ To set STS endpoint resolution logic, use the `AWS_STS_REGIONAL_ENDPOINTS` envir +If you have data stored in AWS that uses a particular encoding, you should make sure that your systems are configured to accept that encoding. For instance, if you have unicode characters as part of a key on EC2 you will need to make sure that your locale is set to a unicode-compatible locale. How you configure your locale will depend on your operating system and your specific IT requirements. One option for UNIX systems is the `LC_ALL` environment variable. Setting `LC_ALL=en_US.UTF-8`, for instance, would give you a United States English locale which is compatible with unicode. @@ -374 +375 @@ To set STS endpoint resolution logic, use the `AWS_STS_REGIONAL_ENDPOINTS` envir -Uses the STS endpoint that corresponds to the configured region. For example if the client is configured to use `us-west-2`, all calls to STS will be make to the `sts.us-west-2.amazonaws.com` regional endpoint instead of the global `sts.amazonaws.com` endpoint. +To set the encoding that is used when reading from text files, you can use the `AWS_CLI_FILE_ENCODING` environment variable. For example, if you use Windows with default encoding `CP1252`, setting `AWS_CLI_FILE_ENCODING=UTF-8` would make CLI ignore locale encoding and open text files using `UTF-8`. @@ -376 +377 @@ Uses the STS endpoint that corresponds to the configured region. For example if - * `legacy` +To set the encoding used for the CLI’s output, you can use the `AWS_CLI_OUTPUT_ENCODING` environment variable. For example, if you use Windows with the default encoding `CP1252`, setting `AWS_CLI_OUTPUT_ENCODING=UTF-8` would make CLI ignore the locale encoding and format its output using `UTF-8`. @@ -377,0 +379 @@ Uses the STS endpoint that corresponds to the configured region. For example if +Refer to [Python’s Standard Encodings documentation](https://docs.python.org/3/library/codecs.html#standard-encodings) for possible values for both settings. @@ -379 +381 @@ Uses the STS endpoint that corresponds to the configured region. For example if -Uses the global STS endpoint, `sts.amazonaws.com`, for the following configured regions: +### Pager¶ @@ -381,16 +383 @@ Uses the global STS endpoint, `sts.amazonaws.com`, for the following configured - * `ap-northeast-1` - * `ap-south-1` - * `ap-southeast-1` - * `ap-southeast-2` - * `aws-global` - * `ca-central-1` - * `eu-central-1` - * `eu-north-1` - * `eu-west-1` - * `eu-west-2` - * `eu-west-3` - * `sa-east-1` - * `us-east-1` - * `us-east-2` - * `us-west-1` - * `us-west-2` +The AWS CLI uses a pager for output data that does not fit on the screen. @@ -398 +385 @@ Uses the global STS endpoint, `sts.amazonaws.com`, for the following configured -All other regions will use their respective regional endpoint. +On Linux/MacOS, `less` is used as the default pager. On Windows, the default is `more`. @@ -399,0 +387 @@ All other regions will use their respective regional endpoint. +#### Configuring pager¶ @@ -400,0 +389 @@ All other regions will use their respective regional endpoint. +You can override the default pager with the following configuration options. These are in order of precedence: @@ -401,0 +391,3 @@ All other regions will use their respective regional endpoint. + * `AWS_PAGER` environment variable + * `cli_pager` shared config variable + * `PAGER` environment variable @@ -403 +394,0 @@ All other regions will use their respective regional endpoint. -### Retry Configuration¶ @@ -405 +395,0 @@ All other regions will use their respective regional endpoint. -These configuration variables control how the AWS CLI retries requests. @@ -407,3 +397 @@ These configuration variables control how the AWS CLI retries requests. -`max_attempts` - An integer representing the maximum number attempts that will be made for a single request, including the initial attempt. For example, setting this value to 5 will result in a request being retried up to 4 times. If not provided, the number of retries will default to whatever is modeled, which is typically 5 total attempts in the `legacy` retry mode, and 3 in the `standard` and `adaptive` retry modes. -`retry_mode` +If you set any of the configuration options to an empty string (e.g. `AWS_PAGER=""`) or use `--no-cli-pager` option in the command line the AWS CLI will not send the output to a pager. @@ -410,0 +399 @@ These configuration variables control how the AWS CLI retries requests. +##### Examples¶ @@ -412 +401 @@ These configuration variables control how the AWS CLI retries requests. -A string representing the type of retries the AWS CLI will perform. Value values are: +To disable the pager for `default` profile: @@ -414,4 +402,0 @@ A string representing the type of retries the AWS CLI will perform. Value values -> * `legacy` \- The pre-existing retry behavior. This is default value if no retry mode is provided. -> * `standard` \- A standardized set of retry rules across the AWS SDKs. This includes a standard set of errors that are retried as well as support for retry quotas, which limit the number of unsuccessful retries an SDK can make. This mode will default the maximum number of attempts to 3 unless a `max_attempts` is explicitly provided. -> * `adaptive` \- An experimental retry mode that includes all the functionality of `standard` mode along with automatic client side throttling. This is a provisional mode that may change behavior in the future. -> @@ -418,0 +404 @@ A string representing the type of retries the AWS CLI will perform. Value values + aws configure set cli_pager "" --profile default @@ -420 +405,0 @@ A string representing the type of retries the AWS CLI will perform. Value values -### Amazon S3¶ @@ -422 +407 @@ A string representing the type of retries the AWS CLI will perform. Value values -There are a number of configuration variables specific to the S3 commands. See [AWS CLI S3 Configuration](s3-config.html) (`aws help topics s3-config`) for more details. +To disable the pager for all profiles in the current terminal session: @@ -424 +408,0 @@ There are a number of configuration variables specific to the S3 commands. See [ -## OS Specific Configuration¶ @@ -426 +410,9 @@ There are a number of configuration variables specific to the S3 commands. See [ -### Locale¶ + export AWS_PAGER="" - for Linux + + set AWS_PAGER="" - for Windows cmd + + +To disable the pager for one command call: + + + aws <command> <sub-command> --no-cli-pager @@ -428 +420,24 @@ There are a number of configuration variables specific to the S3 commands. See [ -If you have data stored in AWS that uses a particular encoding, you should make sure that your systems are configured to accept that encoding. For instance, if you have unicode characters as part of a key on EC2 you will need to make sure that your locale is set to a unicode-compatible locale. How you configure your locale will depend on your operating system and your specific IT requirements. One option for UNIX systems is the `LC_ALL` environment variable. Setting `LC_ALL=en_US.UTF-8`, for instance, would give you a United States English locale which is compatible with unicode. + +#### Pager settings¶ + +If the `LESS` environment variable is not set the AWS CLI will set it to `FRX` (see “less” manual page for more information about possible options <https://man7.org/linux/man-pages/man1/less.1.html>) in order to set the appropriate flags. If you set the `LESS` env var, we will not clobber it with ours (e.g. `FRX`). Be aware that different shells can have different default values for the `LESS` environment variable that can cause unexpected behavior of AWS CLI output + +You can also set flags when specifying the pager and those will combine with any environment variables we set (e.g. `AWS_PAGER="less -S"` will make it less `-FRXS`). The behavior of combining flags is a feature of `less`. You can also negate flags we set by specifying it on the command line: (e.g. `AWS_PAGER="less -+F"` will deactivate the quit if one screen behavior) + +For Windows, `more` is used with no additional environment variables. + +## Plugins¶ + +### Warning + +Plugin support in the AWS CLI v2 is completely provisional and intended to help users migrate from AWS CLI v1 until a stable plugin interface is released. There are no guarantees that a particular plugin or even the CLI plugin interface will be supported in future versions of the AWS CLI v2. If you are relying on plugins, be sure to lock to a particular version of the CLI and test functionality of your plugin when you do upgrade. + +To enable plugin support, create `[plugins]` section in your `~/.aws/config` file: + + + [plugins] + cli_legacy_plugin_path = <path-to-plugins>/python3.8/site-packages + <plugin-name> = <plugin-module> + + +In the `[plugins]` section, you must define the `cli_legacy_plugin_path` variable and set its value to the Python site packages path that your plugin lives in. Once defined, you can configure plugins by providing a name for the plugin, `plugin-name`, and the Python module, `plugin-module`, that contains the source code for your plugin. Then, the CLI loads each plugin by importing their `plugin-module` and calling their `awscli_initialize` function. @@ -440 +455 @@ If you have data stored in AWS that uses a particular encoding, you should make - * [AWS CLI 1.40.40 Command Reference](../index.html) » + * [AWS CLI 2.27.42 Command Reference](../index.html) » @@ -444,0 +460,2 @@ If you have data stored in AWS that uses a particular encoding, you should make + +© Copyright 2025, Amazon Web Services. Created using [Sphinx](https://www.sphinx-doc.org/).