AWS CLI v1-to-v2 Migration Tool

A command-line tool that lints bash scripts for AWS CLI v1 usage and updates them to avoid breaking changes introduced in AWS CLI v2. Not all breaking changes can be detected statically, thus not all of them are supported by this tool.

For a full list of the breaking changes introduced with AWS CLI v2, see Breaking changes between AWS CLI version 1 and AWS CLI version 2.

Jump to:

• Installation
• Usage
• Supported Breaking Changes
• Backwards Compatibility Policy
• Contributing
• Getting Help

Installation

Most users should install AWS CLI v1-to-v2 Migration Tool via pip in a virtualenv:

$ python3 -m pip install aws-cli-migrate

or, if you are not installing in a virtualenv, to install globally:

$ sudo python3 -m pip install aws-cli-migrate

or for your user:

$ python3 -m pip install --user aws-cli-migrate

If you have the aws-cli-migrate package installed and want to upgrade to the latest version, you can run:

$ python3 -m pip install --upgrade aws-cli-migrate

This will install the aws-cli-migrate package as well as all dependencies.

Usage

Dry-run mode (default)

Display issues without modifying the script:

migrate-aws-cli --script upload_s3_files.sh

Auto-fix mode

Automatically update the input script:

migrate-aws-cli --script upload_s3_files.sh --fix

Optionally, supply an output path to write the updated script, rather than updating the input bash script:

migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix

Interactive mode

Review and accept/reject each change individually:

migrate-aws-cli --script upload_s3_files.sh --interactive --output upload_s3_files_v2.sh

In interactive mode, you can:

• Press y to accept the current change
• Press n to skip the current change
• Press a to accept all findings with the current type
• Press r to reject all findings with the current type
• Press u to accept all remaining changes
• Press s to save and exit
• Press q to quit without saving

Supported Breaking Changes

The AWS CLI v1-to-v2 Migration Tool lints bash scripts for usage of AWS CLI v1 commands that are likely to face breaking changes after upgrading to AWS CLI v2. Additionally, the migration tool can automatically modify bash scripts to prevent breakage caused by breaking changes that would be caused by upgrading to AWS CLI v2.

Using the migration tool does not guarantee that all breaking changes will be fully prevented. We recommend that users upgrading from AWS CLI v1 to AWS CLI v2 read Breaking changes between AWS CLI version 1 and AWS CLI version 2 in New features and changes in the AWS CLI version 2.

The table below describes which breaking changes the migration tool can detect or automatically fix.

Breaking Change	Detection	Auto-fix
Environment variable added to set text file encoding	❌ No	❌ No
Binary parameters are passed as base64-encoded strings by default	✅ Yes	✅ Yes
Improved Amazon S3 handling of file properties and tags for multipart copies	✅ Yes	✅ Yes
No automatic retrieval of http:// or https:// URLs for parameters	❌ No	❌ No
Pager used for all output by default	✅ Yes	✅ Yes
Timestamp output values are standardized to ISO 8601 format	❌ No	❌ No
Improved handling of CloudFormation deployments that result in no changes	✅ Yes	✅ Yes
Changed default behavior for Regional Amazon S3 endpoint for us-east-1 Region	❌ No	❌ No
Changed default behavior for Regional AWS STS endpoints	❌ No	❌ No
ecr get-login removed and replaced with ecr get-login-password	✅ Yes	❌ No
AWS CLI version 2 support for plugins is changing	❌ No	❌ No
Hidden alias support removed	✅ Yes	✅ Yes
The api_versions configuration file setting is not supported	❌ No	❌ No
AWS CLI version 2 uses only Signature v4 to authenticate Amazon S3 requests	❌ No	❌ No
AWS CLI version 2 is more consistent with paging parameters	✅ Yes	❌ No
AWS CLI version 2 provides more consistent return codes across all commands	❌ No	❌ No

Backwards Compatibility Policy

The AWS CLI v1-to-v2 Migration Tool does not guarantee backwards compatibility. In particular, this tool may face breaking changes in any future versions.

See CHANGELOG.md for details on the changes introduced in each update of the AWS CLI v1-to-v2 Migration Tool.

Contributing

If you'd like to contribute to the project, please see our Contributing Guide for development setup instructions and guidelines.

Getting Help

The best way to interact with our team is through GitHub. You can open an issue and choose the templates for the AWS CLI v1-to-v2 Migration Tool.

If you have a support plan with AWS Support, you can also create a new support case.

Please check for open similar issues before opening another one.