New features and changes in the AWS CLI version 2

This topic describes new features and changes in behavior between AWS CLI version 1 and AWS CLI version 2. These changes might require you to update your scripts or commands to get the same behavior in version 2 as you did in version 1.

AWS CLI version 2 new features

The AWS CLI version 2 is the most recent major version of the AWS CLI and supports all of the latest features. Some features introduced in version 2 are not backported to version 1 and you must upgrade to access those features. These features include the following:

Breaking changes between AWS CLI version 1 and AWS CLI version 2

This sections describes all of the changes in behavior between AWS CLI version 1 and AWS CLI version 2. These changes might require you to update your scripts or commands to get the same behavior in version 2 as you did in version 1.

Environment variable added to set text file encoding

By default, text files for Blob use the same encoding as the installed locale. Because the AWS CLI version 2 uses an embedded version of Python, the PYTHONUTF8 and PYTHONIOENCODING environment variables are not supported. To set encoding for text files to be different from the locale, use the AWS_CLI_FILE_ENCODING environment variable. The following example sets the AWS CLI to open text files using UTF-8 on Windows.

AWS_CLI_FILE_ENCODING=UTF-8

For more information, see Configuring environment variables for the AWS CLI .

Binary parameters are passed as base64-encoded strings by default

In the AWS CLI, some commands required base64-encoded strings, while others required UTF-8-encoded byte strings. In the AWS CLI version 1, passing data between two encoded string types often required some intermediate processing. The AWS CLI version 2 makes handling binary parameters more consistent, which helps pass values from one command to another more reliably.

By default, the AWS CLI version 2 passes all binary input and binary output parameters as the base64-encoded string blobs (binary large object). For more information, see Blob.

To revert to the AWS CLI version 1 behavior, use the cli_binary_format file configuration or the --cli-binary-format parameter.

Improved Amazon S3 handling of file properties and tags for multipart copies

When you use the AWS CLI version 1 commands in the aws s3 namespace to copy a file from one S3 bucket location to another, and that operation uses multipart copy, no file properties from the source object are copied to the destination object.

By default, the corresponding commands in the AWS CLI version 2 transfer all tags and some of the properties from the source to the destination copy. Compared to the AWS CLI version 1, this can result in more AWS API calls being made to the Amazon S3 endpoint. To change the default behavior for s3 commands in AWS CLI version 2 , use the --copy-props parameter.

For more information, see File properties and tags in multipart copies.

No automatic retrieval of http:// or https:// URLs for parameters

The AWS CLI version 2 does not perform a GET operation when a parameter value begins with http:// or https://, and does not use the returned content as the parameter value. As a result, the associated command line option cli_follow_urlparam is removed from the AWS CLI version 2.

If you need to retrieve a URL and pass the URL contents into a parameter value, we recommend that you use curl or a similar tool to download the contents of the URL to a local file. Then, use the file:// syntax to read the contents of that file and use it as the parameter value.

For example, the following command no longer tries to retrieve the contents of the page found at http://www.example.com and pass those contents as the parameter. Instead, it passes the literal text string https://example.com as the parameter.

$ aws ssm put-parameter \
    --value http://www.example.com \
    --name prod.microservice1.db.secret \
    --type String 2

If you need to retrieve and use the contents of a web URL as a parameter, you can do the following in version 2.

$ curl https://my.example.com/mypolicyfile.json -o mypolicyfile.json
$ aws iam put-role-policy \
    --policy-document file://./mypolicyfile.json \
    --role-name MyRole \
    --policy-name MyReadOnlyPolicy

In the preceding example, the -o parameter tells curl to save the file in the current folder with the same name as the source file. The second command retrieves the content of that downloaded file and passes the content as the value of --policy-document.

Pager used for all output by default

By default, the AWS CLI version 2 returns all output through your operating system’s default pager program. This program is the less program on Linux or macOS, and the more program on Windows. This can help you navigate a large amount of output from a service by displaying that output one page at a time.

You can configure the AWS CLI version 2 to use a different paging program or none at all. For more information, see Client-side pager.

Timestamp output values are standardized to ISO 8601 format

By default, the AWS CLI version 2 returns all timestamp response values in the ISO 8601 format. In AWS CLI version 1, commands returned timestamp values in whatever format was returned by the HTTP API response, which could vary from service to service.

To see timestamps in the format returned by the HTTP API response, use the wire value in your config file. For more information, see cli_timestamp_format.

Improved handling of CloudFormation deployments that result in no changes

By default in the AWS CLI version 1, if you deploy a AWS CloudFormation template that results in no changes, the AWS CLI returns a failed error code. This causes problems if you don't consider that to be an error and you want your script to continue. You can work around this in the AWS CLI version 1 by adding the flag -–no-fail-on-empty-changeset, which returns 0.

Since this is a common use case, the AWS CLI version 2 defaults to returning a successful exit code of 0 when there is no change caused by a deployment and the operation returns an empty changeset.

To revert to the original behavior, add the flag --fail-on-empty-changeset.

Changed default behavior for Regional Amazon S3 endpoint for us-east-1 Region

When you configure theAWS CLI version 1 to use the us-east-1 Region, the AWS CLI uses the global s3.amazonaws.com endpoint that is physically hosted in the us-east-1 Region. The AWS CLI version 2 uses the true Regional endpoint s3.us-east-1.amazonaws.com when that Region is specified. To force the AWS CLI version 2 to use the global endpoint, you can set the Region for a command to aws-global.

Changed default behavior for Regional AWS STS endpoints

By default, the AWS CLI version 2 sends all AWS Security Token Service (AWS STS) API requests to the Regional endpoint for the currently configured AWS Region.

By default, the AWS CLI version 1 sends AWS STS requests to the global AWS STS endpoint. You can control this default behavior in version 1 by using the sts_regional_endpoints setting.

ecr get-login removed and replaced with ecr get-login-password

The AWS CLI version 2 replaces the command aws ecr get-login with the aws ecr get-login-password command that improves automated integration with container authentication.

The aws ecr get-login-password command reduces the risk of exposing your credentials in the process list, shell history, or other log files. It also improves compatibility with the docker login command for better automation.

The aws ecr get-login-password command is available in the AWS CLI version 1.17.10 and later, and the AWS CLI version 2. The earlier aws ecr get-login command is still available in the AWS CLI version 1 for backward compatibility.

With the aws ecr get-login-password command, you can replace the following code that retrieves a password.

$ (aws ecr get-login --no-include-email)

To reduce the risk of exposing the password to the shell history or logs, use the following example command instead. In this example, the password is piped directly to the docker login command, where it is assigned to the password parameter by the --password-stdin option.

$ aws ecr get-login-password | docker login --username AWS --password-stdin MY-REGISTRY-URL

For more information, see aws ecr get-login-password in the AWS CLI version 2 Reference Guide.

AWS CLI version 2 support for plugins is changing

Plugin support in the AWS CLI version 2 is completely provisional and is intended to help users migrate from AWS CLI version 1 until a stable, updated plugin interface is released. There are no guarantees that a particular plugin or even the AWS CLI plugin interface will be supported in future versions of the AWS CLI version 2. If you rely on plugins, be sure to lock into a particular version of the AWS CLI and test the functionality of your plugin when you do upgrade.

To enable plugin support, create a [plugins] section in your ~/.aws/config.

[plugins]
cli_legacy_plugin_path = <path-to-plugins>/python3.7/site-packages
<plugin-name> = <plugin-module>

In the [plugins] section, define the cli_legacy_plugin_path variable and set its value to the Python site packages path where your plugin module is. Then, you can configure a plugin by providing a name for the plugin (plugin-name) and the file name of the Python module (plugin-module) that contains the source code for your plugin. The AWS CLI loads each plugin by importing its plugin-module and calling its awscli_initialize function.

Hidden alias support removed

AWS CLI version 2 no longer supports the following hidden aliases that were supported in version 1.

In the following table, the first column displays the service, command, and parameter that work in all versions, including the AWS CLI version 2. The second column displays the alias that no longer works in the AWS CLI version 2.

The api_versions configuration file setting is not supported

The AWS CLI version 2 doesn't support calling earlier versions of AWS service APIs by using the api_versions configuration file setting. All AWS CLI commands now call the latest version of the service APIs that are currently supported by the endpoint.

AWS CLI version 2 uses only Signature v4 to authenticate Amazon S3 requests

The AWS CLI version 2 doesn't support earlier signature algorithms to cryptographically authenticate service requests sent to Amazon S3 endpoints. This signing happens automatically with every Amazon S3 request and only the Signature Version 4 Signing Process is supported. You can't configure the signature version. All Amazon S3 bucket presigned URLs now use only SigV4 and have a maximum expiration duration of one week.

AWS CLI version 2 is more consistent with paging parameters

In the AWS CLI version 1, if you specify pagination parameters on the command line, then automatic pagination is turned off as expected. However, when you specify pagination parameters by using a file with the ‐‐cli-input-json parameter, automatic pagination was not turned off, which could result in unexpected output. The AWS CLI version 2 turns off automatic pagination regardless of how you provide the parameters.

AWS CLI version 2 provides more consistent return codes across all commands

The AWS CLI version 2 is more consistent across all commands and properly returns an appropriate exit code compared to the AWS CLI version 1. We also added exit codes 252, 253, and 254. For more information on exit codes, see Command line return codes in the AWS CLI.

If you have a dependency on how the AWS CLI version 1 uses return code values, we recommend checking the exit codes to make sure that you're getting the values you expect.