Set Up Your Development Environment

This topic describes how to set up your local development environment so you can build Alexa+ add-ons.

Prerequisites

Software requirements

• 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.

Required accounts

• 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.

Hardware requirements (optional — for physical device testing)

• 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

To get started, you need the Alexa AI CLI. You use the Alexa AI CLI to create the starter package from a list of categories. You can deploy the package to Alexa+ using the Alexa AI CLI and use AWS CDK for cloud resource management on AWS.

Step 1: Set up your AWS account

Log in to the AWS account that you provided to the Alexa Solutions Architect when you do these steps.

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

Set up two AWS profiles — one for the IAM user's base credentials, and one for role assumption.

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-..."
    }
   

With this setup, any AWS CLI command run with --profile alexa-ai automatically assumes the AddOn3PDeveloperToolsRead role using your IAM user credentials.

Step 3: Configure Git for CodeCommit

Run the following commands to enable Git to authenticate against CodeCommit using the alexa-ai profile:

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

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

This ensures that when the alexa-ai new action command clones a template from CodeCommit, Git automatically uses the assumed role credentials.

Step 4: Configure npm registry (CodeArtifact)

Authenticate npm against the Alexa AI private CodeArtifact registry:

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

This command configures your local .npmrc to route @alexa-ai/* scoped packages through the private registry.

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

If you are building a Category Action Add-on, you need to configure your default AWS profile for CDK deployment. Use the IAM User credentials where you have AdministratorAccess privileges assigned. If you are using the same AWS account from earlier steps, use the same Access Key credentials:

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>

This avoids managing a separate set of credentials if your IAM user already has AdministratorAccess. For details about how to attach AdministratorAccess, see Step 1: Set up your AWS account.

Step 6: Install Alexa AI CLI

After completing the previous configuration steps, install the 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

After completing setup, proceed to create your add-on:

• 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

---

---

Last updated: Jul 15, 2026