Workflows

Executing Transformations

This section describes the different ways to execute transformations and options for controlling execution behavior.

Execution Modes

AWS Transform custom supports three execution modes to accommodate different workflows.

Interactive Conversational Mode

Start the CLI with atx and ask the agent to execute a transformation through natural language. This mode allows you to have a full conversation with the agent, interrupt execution at any point, and provide feedback during the transformation process.

Use this mode when you want maximum control and the ability to guide the agent through complex scenarios.

Direct Interactive Execution

Use atx custom def exec -n <transformation-name> -p <path> to start a specific transformation interactively. This mode allows you to review and interact with the agent at the beginning, during, or at the end of execution. The agent will pause at key decision points and ask for your input.

This is ideal for testing and refining transformations before running them autonomously.

Non-Interactive/Headless Mode

Use atx custom def exec -n <transformation-name> -p <path> -x -t for full automation. The -x flag enables non-interactive mode, and the -t flag automatically trusts all tools without prompting.

This mode is designed for CI/CD pipeline integration and bulk execution where no human intervention is available or desired.

Common Command Flags

When executing transformations with atx custom def exec, the following flags are commonly used:

Using Configuration Files

AWS Transform custom supports optional configuration files in YAML or JSON format. Configuration files allow you to specify execution parameters and provide additional context to the agent.

To use a configuration file:

atx custom def exec --configuration file://config.yaml

You can also provide configuration as inline key-value pairs:

atx custom def exec --configuration "key=value,key2=value2"

Example configuration file (config.yaml):

codeRepositoryPath: ./my-project
transformationName: my-transformation
buildCommand: mvn clean install
additionalPlanContext: |
  The target Java version to upgrade to is Java 17.
  Ensure compatibility with our internal logging framework version 2.3.
validationCommands: |
  mvn test
  mvn verify

The additionalPlanContext parameter provides extra context for the agent's execution plan. This is especially useful with AWS-managed transformations to customize their behavior for your specific needs.

Build and Validation Commands

The build or validation command is an optional parameter that specifies how to validate your code during the transformation process. AWS Transform custom will attempt to infer the best build command based on the transformation if not specified, though it is recommended to be specific for quality.

Examples of build and validation commands:

Even for languages or transformations that don't require building, providing a command that validates the results and returns issues if validation fails is very important to improve transformation quality.

If no build or validation is needed, use "noop" as the value.

Controlling Learning Behavior

By default, AWS Transform custom extracts knowledge items from every transformation execution. You can prevent learning for specific executions.

To prevent learning from an execution:

atx custom def exec -n my-transformation -p ./my-project -d

The -d or --do-not-learn flag opts out of allowing knowledge item extraction from the current execution.

Resuming Conversations

AWS Transform custom allows you to resume previous conversations within 30 days of creation.

To resume the most recent conversation:

atx --resume

To resume a specific conversation:

atx --conversation-id <conversation-id>

Continual Learning

This section describes how to manage knowledge items created by continual learning.

Understanding Knowledge Items

Knowledge items are automatically extracted learnings from transformation executions. These are created asynchronously by the continual learning system based on:

Knowledge items start in a "not approved" state and must be explicitly approved by transformation owners before they can be used in future executions. Unlike references which you provide upfront, knowledge items accumulate over time as the transformation is executed across different codebases.

Listing Knowledge Items

View all knowledge items for a transformation definition.

To list knowledge items:

atx custom def list-ki -n my-transformation

This displays all knowledge items that have been extracted from executions of the specified transformation definition.

Viewing Knowledge Item Details

View detailed information about a specific knowledge item.

To view knowledge item details:

atx custom def get-ki -n my-transformation --id <knowledge-item-id>

Enabling and Disabling Knowledge Items

Control which knowledge items are applied to future transformations.

To enable a knowledge item:

atx custom def update-ki-status -n my-transformation --id <knowledge-item-id> --status ENABLED

To disable a knowledge item:

atx custom def update-ki-status -n my-transformation --id <knowledge-item-id> --status DISABLED

Configuring Auto-Approval

You can configure whether knowledge items are automatically enabled or require manual approval.

To enable auto-approval for all knowledge items:

atx custom def update-ki-config -n my-transformation --auto-enabled TRUE

To disable auto-approval:

atx custom def update-ki-config -n my-transformation --auto-enabled FALSE

Deleting Knowledge Items

Permanently remove knowledge items that are not useful.

To delete a knowledge item:

atx custom def delete-ki -n my-transformation --id <knowledge-item-id>

Exporting Knowledge Items

Export all knowledge items for a transformation to markdown format for review or documentation.

To export knowledge items:

atx custom def export-ki-markdown -n my-transformation

Advanced Configuration

This section describes advanced features and configuration options for AWS Transform custom.

Environment Variables

You can customize CLI behavior using environment variables.

ATX_SHELL_TIMEOUT

Override the default timeout for shell commands (900 seconds/15 minutes).

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

This is useful for large codebases or long-running build processes.

ATX_DISABLE_UPDATE_CHECK

Disable automatic version checks and update notifications during command execution.

export ATX_DISABLE_UPDATE_CHECK=true

Trust Settings

Trust settings allow you to pre-approve specific tools and commands to execute without prompts. These settings are configured in the ~/.atx/trust-settings.yaml file.

The file contains two lists:

Default trusted tools:

Editing trust settings:

You can manually edit the trust-settings.yaml file to add or remove trusted tools and commands. The trustedShellCommands list supports wildcard patterns using * for flexible command matching.

Examples:

Session-level trust:

During interactive prompts, you can choose:

Session-level trust settings are temporary and reset when the CLI restarts, providing temporary approval without permanently modifying trust-settings.yaml.

Model Context Protocol (MCP) Servers

The AWS Transform CLI supports Model Context Protocol (MCP) servers, which extend its functionality with additional tools.

Configuration:

Configure MCP servers in the ~/.atx/mcp.json file.

Managing MCP servers:

View status:

atx mcp tools -s

List available tools:

atx mcp tools -l

Refresh MCP servers:

atx mcp tools -r

Tags and Organization

You can organize transformations with tags for access control and categorization.

To list tags for a transformation:

atx custom def list-tags --arn <transformation-arn>

To add tags to a transformation:

atx custom def tag --arn <transformation-arn> --tags '{"env":"prod","team":"backend"}'

To remove tags from a transformation:

atx custom def untag --arn <transformation-arn> --tag-keys "env,team"

Tags can be used for grouped access control in IAM policies. You can create policies that grant permissions to all transformations with specific tags (e.g., all transformations tagged with team:frontend or environment:production).

Logs

AWS Transform CLI maintains two types of logs for troubleshooting and debugging.

Conversation logs:

Location: ~/.atx/<conversation_id>/logs/<timestamp>-conversation.log

These logs contain the full conversation history for a specific session.

Developer debug logs:

Locations:

These logs provide advanced troubleshooting information for the CLI itself.

CLI Updates

Keep your CLI up to date to access new features and improvements.

To check for updates:

atx update --check

To update to the latest version:

atx update

To update to a specific version:

atx update --target-version <version>

Create Custom Transformations

This section describes how to create, modify, and manage custom transformation definitions.

Creating a New Transformation

Use the interactive CLI to create a new transformation definition.

To create a transformation definition

Best practices for creating transformations:

Providing Reference Materials

You can provide reference files to AWS Transform custom by specifying file paths during the conversation.

Recommended types of reference files:

To provide a reference file:

Take a look at the documentation here: /path/to/migration-guide.md

You can also provide a directory containing multiple reference files:

Take a look at the docs we have here: /path/to/docs/

Modifying an Existing Transformation

You can modify custom transformations both before and after saving them as drafts or publishing them. You cannot modify AWS-managed transformations. If you need to customize them, you can provide additional context using the config file.

To modify an existing transformation

Publishing and Managing Transformations

You can publish and manage your transformations using the interactive experience or with the following commands.

To save a transformation as a draft:

atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

To publish a transformation:

atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

To list available transformations:

atx custom def list

To download a transformation definition:

atx custom def get -n my-transformation

This downloads the transformation definition to your current working directory. You can specify a target directory with the --td flag and a version with the --tv flag.

To delete a transformation definition:

atx custom def delete -n my-transformation

Managing Transformation Versions

AWS Transform custom maintains versions of your transformation definitions. You can specify a version when executing or downloading a transformation.

To execute a specific version:

atx custom def exec -n my-transformation --tv v1 -p ./my-project

To download a specific version:

atx custom def get -n my-transformation --tv v1

If no version is specified, the latest version is used.