Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Preferences
Contact Us
Feedback
AWS Documentation
Create an AWS Account

Running a transformation on the command line with Amazon Q Developer

PDF
RSS
Focus mode
Running a transformation on the command line with Amazon Q Developer - Amazon Q Developer
PrerequisitesStep 1: Choose authentication method and add permissionsStep 2: Install the toolStep 3: Configure and authenticateStep 4: Run a transformation
Transforming code with Amazon Q on the command line is in preview, and is subject to change.

Complete these steps to transform your code on the command line with the Amazon Q Developer command line tool.

Prerequisites

Before you begin a transformation on the command line, the following prerequisites must be met:

  • If you're upgrading your Java code version, your project meets the prerequisites for upgrading Java versions with Amazon Q.

  • If you're converting embedded SQL in a Java application, your application meets the prerequisites for converting embedded SQL with Amazon Q.

  • You have Python installed on your command line environment. This is how you will install the command line tool. The minimum supported Python version is 3.12.

  • You are running the transformation on macOS or Linux.

  • The size of your application is 2 GB or smaller.

  • If you are performing custom transformations, you have installed the ast-grep tool. To install and set up ast-grep, see Installation in the ast-grep documentation.

Step 1: Choose authentication method and add permissions

You can authenticate with AWS Identity and Access Management (IAM) or IAM Identity Center to run transformations on the command line. Regardless of the authentication method you use, ensure you have the proper permissions.

Note

Customer managed keys aren't supported for transformations performed on the command line.

Add permissions

The IAM identity associated with either the AWS CLI profile or the Amazon Q Developer subscription you are using to authenticate must have permissions to perform transformations on the command line. Before you proceed, ensure your IAM identity has the permissions defined in Allow users to run transformations on the command line.

Authenticate with IAM

Note

You can't use IAM to authenticate with a Amazon Q Developer subscription.

To authenticate with IAM, you must:

You can specify this configuration on your command line by running aws configure after installing the AWS CLI.

You provide the AWS CLI profile you configured in Step 3: Configure and authenticate.

Authenticate with IAM Identity Center through a Amazon Q Developer subscription

To authenticate with IAM Identity Center, you must be subscribed to Amazon Q Developer Pro and provide the Start URL to authenticate through your subscription. You or your administrator can find the Start URL in the Amazon Q Developer console. For more information see, Managing account details in Amazon Q Developer.

To add required permissions, see Add permissions.

You provide the Start URL in Step 3: Configure and authenticate.

Step 2: Install the tool

  1. Download the Amazon Q command line tool for transformations.

    To download a previous version of the command line tool, see Version history.

  2. We recommend that you set up a virtual environment in Python to install the tool. To create a virtual environment, open a terminal window and run:

    python -m venv qct-cli

  3. To activate the virtual environment, run: 

    source qct-cli/bin/activate

  4. To install the tool on your command line, run:

    pip install amzn_qct_cli-0.5.1-py3-none-any.whl
    Note

    If you are using an older version of the command line tool for transformations, replace 0.5.1 with the version you downloaded.

  5. To verify that the tool was installed, run:

    which qct

Step 3: Configure and authenticate

Before you can begin a transformation, you must authenticate to the AWS CLI and provide configuration details for your transformation.

  1. If you're authenticating with IAM and you haven't already configured the AWS CLI, run the following command to provide authentication details. For requirements to authenticate with IAM on the AWS CLI, see Authenticate with IAM. 

    aws configure

  2. To start the transformation configuration process, run the following command:

    qct configure

  3. First, your Maven version is verified. If you have at least the minimum supported version, you will see the following output: 

    Running command: mvn --version at: path/to/current/directory 
Your Maven version is supported for transformations.

    If you don’t have a supported version of Maven, you must update it to continue. For more information, see the Prerequisites.

  4. You are then prompted to enter a JDK path for each supported Java version. You only need to specify the path to the JDK of the Java version you are upgrading.

  5. Next, you are prompted to choose your authentication method.

    1. To authenticate with IAM credentials stored in your AWS CLI profile, enter 1. You can specify a specific profile name or press enter to use the default profile.

      If you'd like to add tags to your transformation, you can supply a CSV file where your tags are stored. The CSV must have two columns, with headers titled key and value, where tag key-value pairs are listed. To add these tags to your transformation, enter the path to the CSV file where tags are stored.

    2. To authenticate with IAM Identity Center through your Amazon Q Developer subscription, enter 2, and then enter the start URL for your subscription profile.

      Next, enter the AWS Region where you were subscribed in the following format: us-east-1. For a list of supported Regions, see Supported Regions. For a list of Region codes, see Regional endpoints in the AWS General Reference guide.

  6. If you're upgrading your code's Java version, you have the option to receive your code suggestions from Amazon Q in one commit or multiple commits. Amazon Q will split the upgraded code into multiple commits by default. If you want all your code changes to appear in one commit, enter the letter 'O' for one commit when prompted.

    For more information on how Amazon Q splits up the code changes, see Reviewing the transformation summary and accepting changes.

  7. Your configuration preferences are saved to a configuration.ini file.

Step 4: Run a transformation

Choose the type of transformation you're performing to see the required configuration and commands.

For information on running custom transformations, see Customizing transformations.

Java upgrade

  1. Run the following command to start a transformation for a Java upgrade. Replace <path-to-folder> with the path to the folder with the code you're transforming and <your-target-java-version> with either JAVA_17 or JAVA_21.

    qct transform --source_folder <path-to-folder>
    --target_version <your-target-java-version>

  2. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted.

    Your upgraded code will be committed to the new branch Amazon Q created. Amazon Q will commit the code in one or multiple commits, depending on the selection you made when you ran qct configure.

SQL conversion

Before you begin, make you sure you've read Converting embedded SQL in Java applications with Amazon Q Developer to understand the prerequisites for this type of transformation.

  1. To convert embedded SQL, you must first create a YAML file that contains the path to the schema metadata file from your AWS DMS Schema Conversion.

    Following is the required format of the file: 

    schema_conv_metadata_path: <path-to-metadata-zip-file>

  2. Run the following command to start a transformation for a SQL conversion. Replace <path-to-folder> with the path to the folder with the code you're transforming and <path-to-sql-config-file> with the path to the YAML file you created in step 1.

    qct transform --source_folder <path-to-folder>
    --sql_conversion_config_file <path-to-sql-config-file>

  3. If Amazon Q finds multiple schemas in your schema metadata file, it will stop the transformation and provide a list of the detected schemas. Choose which schema to use for the SQL conversion, and then add a new field schema: <schema-name> to the YAML file.

  4. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted.

    Your upgraded code will be committed to the new branch Amazon Q created.

anchoranchor

  1. Run the following command to start a transformation for a Java upgrade. Replace <path-to-folder> with the path to the folder with the code you're transforming and <your-target-java-version> with either JAVA_17 or JAVA_21.

    qct transform --source_folder <path-to-folder>
    --target_version <your-target-java-version>

  2. Amazon Q begins the transformation. It will output status updates throughout the transformation. When it’s complete, Amazon Q provides the path where the transformation results, logs, and configuration files are outputted.

    Your upgraded code will be committed to the new branch Amazon Q created. Amazon Q will commit the code in one or multiple commits, depending on the selection you made when you ran qct configure.

On this page

Related resources

Using Amazon Q Developer on AWS apps and websites
Using Amazon Q Developer in the IDE
Using Amazon Q Developer on the command line

Related resources

Using Amazon Q Developer on AWS apps and websites
Using Amazon Q Developer in the IDE
Using Amazon Q Developer on the command line
PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.