Set Up Your Development Environment

​

Prerequisites

• Operating System: macOS Sierra or higher or Ubuntu.
• Node.js version 24+: You need npm to install Alexa AI CLI. npm is part of Node.js. Amazon recommends that you use the current release or active LTS version of Node.js. To install or update your version of Node.js, refer to the Node.js downloads page. To determine your version of Node.js, open a command prompt, and type node --version.
• For the Category SDK - Action, you also need the following:
  • Amazon Web Service Cloud Development Kit (AWS CDK). You use AWS CDK to manage and deploy your code to AWS. For details, see Getting started with the AWS CDK.
  • Programming Languages: The Category SDK - Action is available in TypeScript.

• An Alexa developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.
  • Make sure you complete the profile setup in the Alexa App.
  • Ensure you have set the phone number and address, which is required by most of the categories
  • Set preferred marketplace on Retail Website to Alexa+ supported marketplaces.
  • Ensure device’s language is set to Alexa+ supported locales for that marketplace.
  • You can create a core developer account for your organization and add and associate different profiles (such as developers, marketer, analyst, and tester) afterward.
• An Amazon Web Services (AWS) account. The AWS account gives you access to resources as part of the free tier of services.

• An Alexa-enabled device, ideally a multimodal Alexa device, such as Amazon Echo Show. For testing voice-only, consider the Amazon Echo Dot.

​

Install the Alexa AI CLI

​

Step 1: Set up your AWS account

1. Create a new IAM user with programmatic access (Access Key ID + Secret Access Key). Give the user a name that reflects the purpose, such as alexa-ai-tools.
2. Attach the following inline policy to the IAM user to allow role assumption:
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "sts:AssumeRole",
          "Resource": "arn:aws:iam::372468808636:role/AddOn3PDeveloperToolsRead"
        }
      ]
    }
   
3. Optional If you plan to use this same AWS account to host your add-on infrastructure (Lambda, API Gateway, etc.), attach the AdministratorAccess managed policy to the IAM user. This is required for CDK Bootstrap and CDK Deploy. How to attach: IAM Console → Users → select your user → Permissions tab → Add permissions → Attach policies directly → search for  AdministratorAccess  → select → Save.
4. Generate Access Key credentials for the IAM user and note down the Access Key ID and Secret Access Key — you need these in the next step.

​

Step 2: Configure AWS profiles

1. Create the base credential profile (for example, alexa-ai-user):
    aws configure --profile alexa-ai-user
   
   Enter your Access Key ID and Secret Access Key when prompted. You can press Enter to skip region and output format (defaults are fine).
2. Create the alexa-ai profile for CodeArtifact and CodeCommit access:
    aws configure set profile.alexa-ai.role_arn arn:aws:iam::372468808636:role/AddOn3PDeveloperToolsRead
    aws configure set profile.alexa-ai.source_profile alexa-ai-user
    aws configure set profile.alexa-ai.region us-west-2
   
3. Verify role assumption:
    aws sts get-caller-identity --profile alexa-ai
   
   Expected output:
    {
        "UserId": "AROA...:botocore-session-...",
        "Account": "372468808636",
        "Arn": "arn:aws:sts::372468808636:assumed-role/AddOn3PDeveloperToolsRead/botocore-session-..."
    }
   

​

Step 3: Configure Git for CodeCommit

git config --global "credential.https://git-codecommit.us-west-2.amazonaws.com.helper" '!aws codecommit credential-helper --profile alexa-ai $@'

git config --global "credential.https://git-codecommit.us-west-2.amazonaws.com.UseHttpPath" true

​

Step 4: Configure npm registry (CodeArtifact)

aws codeartifact login \
    --tool npm \
    --domain alexa-ai \
    --repository npm-packages \
    --domain-owner 372468808636 \
    --region us-west-2 \
    --namespace @alexa-ai \
    --profile alexa-ai

​

Step 5: Configure AWS CLI default profile for CDK (Category Action add-ons only)

aws configure set aws_access_key_id <YOUR_ACCESS_KEY_ID>
aws configure set aws_secret_access_key <YOUR_SECRET_ACCESS_KEY>
aws configure set region <YOUR_REGION>

​

Step 6: Install Alexa AI CLI

1. Run the following command.
    npm install -g @alexa-ai/cli
   
2. Verify the installation.
    alexa-ai --version
   
3. Configure Alexa authentication. The following command opens a browser for Login with Amazon (LWA) Oath. After you log in, credentials are stored at ~/.alexa-ai/credentials.
    alexa-ai configure
   

​

Next steps

• Create a Category Add-on Manually with the CLI
• Create a Category MCP Add-on
• Create an MCP Add-on (MCP Toolkit)

​

Related topics

• Category SDK Overview
• Alexa+ MCP Toolkit Overview
• Alexa AI CLI Reference
• Troubleshooting the Category SDK