Alexa AI CLI Reference

The Alexa AI CLI lets you manage the lifecycle of your Alexa+ add-ons. Use it to create, deploy, test, and submit add-ons.

Overview

Valid syntax for Alexa AI CLI commands:

alexa-ai [options]
alexa-ai [command] [options]
alexa-ai [command] [subcommand] [options]

The Alexa AI CLI has three types of commands:

• High-level commands handle the add-on workflow by orchestrating multiple steps in a single call. Use these for day-to-day development. Examples include new, deploy, test, and submit.
• Catalog commands give you direct control over individual catalog operations, such as creating, uploading, and associating Point of Interest (POI) and event data. Use these when you need control over catalog management.
• Metrics commands let you discover and query usage metrics for your add-on, including task completion funnels, engagement, and API performance data.

Each CLI command maps to one or more calls to the Alexa Add-on API (AAPI) — the REST API that manages the add-on lifecycle. The configure and new commands are client-side only and don't make any API calls.

Common parameters

The following parameters are available on all Alexa AI CLI commands.

To determine the version of the Alexa AI CLI installed on your computer, run alexa-ai --version.

alexa-ai configure

Sets up CLI authentication through the Login with Amazon (LWA) OAuth flow and stores credentials at ~/.alexa-ai/credentials. Run this command again to refresh credentials for the specified profile.

alexa-ai configure [--profile <profile-name>] [--no-browser]

Example usage  

# Default profile
alexa-ai configure

# Named profile
alexa-ai configure --profile my_dev

# SSH environment
alexa-ai configure --profile my_dev --no-browser

alexa-ai new

Scaffolds a new add-on project locally. Doesn't make any backend calls. Supports both interactive and non-interactive modes.

alexa-ai new [type] [options]

Positional argument

Options

If you omit required options, the CLI prompts for them interactively.

Interactive mode

If you run alexa-ai new without arguments, the CLI prompts you to choose an integration type and then asks for the required values. This is the recommended approach for first-time setup.

Non-interactive mode

Pass all required options on the command line to skip prompts. This is useful for CI/CD pipelines and automation scripts. The CLI silently ignores options that don't apply to the chosen type.

Example usage  

# Interactive — prompts for all values
alexa-ai new

# Interactive — skips the type selection prompt (positional)
alexa-ai new action
alexa-ai new mcp

# Non-interactive Category SDK — all values provided, no prompts
alexa-ai new action --name "My Restaurant" --category restaurant-reservation --language typescript --hosting cdk

# Non-interactive MCP Toolkit — all values provided, no prompts
alexa-ai new mcp --name "Example Travel" --mcp-server-url https://mcp.example-travel.com

Example output  

# Sample output (alexa-ai new mcp --name "Example Travel" --mcp-server-url https://mcp.example-travel.com):

Creating MCP add-on project...
✓ Add-on successfully created at ./example-travel/
  addon-package/
    addon.json
  package.json
  .gitignore

Next steps:
  1. cd example-travel
  2. Review addon-package/addon.json
  3. Run: alexa-ai deploy

alexa-ai deploy

Uploads the add-on package, triggers the build pipeline, and deploys to the development stage. The first deploy creates the add-on with a new add-on ID. Subsequent deploys create new versions by using the ID stored in .alexa-ai/config.json.

alexa-ai deploy [--ignore-hash] [--json]

Flow

1. Computes a SHA-256 hash of the addon-package/ directory. If the hash matches the last deployed package and --ignore-hash isn't set, upload is skipped. Build and deploy still run.
2. Zips the addon-package/ directory and calls POST /v1/addons/uploads to get a pre-signed S3 upload URL.
3. Uploads the ZIP to the pre-signed URL.
4. Calls POST /v1/addons/packages (first deploy) or POST /v1/addons/{addOnId}/packages (subsequent deploys) to trigger the build pipeline. Returns a packageId via the Location response header.
5. Polls GET /v1/addons/{addOnId}/packages/{packageId} until the build reaches a terminal state (BUILT or FAILED).
6. Calls POST /v1/addons/{addOnId}/deployments with the packageId to deploy to the development stage. Returns a deploymentId via the Location response header.
7. Polls GET /v1/addons/{addOnId}/deployments/{deploymentId} until deployment reaches a terminal state (SUCCEEDED or FAILED).
8. Stores the add-on ID and package hash in .alexa-ai/config.json for subsequent operations.

Example usage  

# Deploy to development
alexa-ai deploy

# Deploy to development, force re-upload
alexa-ai deploy --ignore-hash

Example output  

Packaging addon-package/...
✓ Package hash: sha256:a1b2c3d4...
  Uploading package...
✓ Upload complete.
  Building package... ⠋
  Build in progress... (pkg-def456)
✓ Build succeeded.
  Deploying to development stage... ⠋
  Deployment in progress... (deploy-xyz789)
✓ Deployed successfully.
  Add-on ID: amzn1.ask.addon.abc123, Version: 3, Stage: development, Package: pkg-def456

Example JSON output  

{
  "addOnId": "amzn1.ask.addon.abc123",
  "packageId": "pkg-def456",
  "deploymentId": "deploy-xyz789",
  "version": 3,
  "packageHash": "sha256:a1b2c3d4...",
  "status": {
    "value": "SUCCEEDED"
  }
}

Example JSON output (failed)  

{
  "addOnId": "amzn1.ask.addon.abc123",
  "packageId": "pkg-def456",
  "deploymentId": "deploy-xyz789",
  "version": 3,
  "packageHash": "sha256:a1b2c3d4...",
  "status": {
    "value": "FAILED",
    "failureReason": "policy url not present"
  }
}

Possible status values in JSON output:

alexa-ai test

Runs tests against the deployed add-on and returns the test execution results. Deploy the add-on to the target stage before running tests.

alexa-ai test [--stage <stage>] [--test-suite <path>] [--filter <pattern>] [--json]

Flow

1. Reads the test suite from the local test-suites/ directory or the path specified by --test-suite.
2. Calls POST /v1/addons/{addOnId}/stages/{stage}/tests with the test suite. Returns a testExecutionId.
3. Polls GET /v1/addons/{addOnId}/tests/{testExecutionId} until the execution reaches a terminal state (COMPLETED or SYSTEM_ERROR).
4. Displays a summary of passed and failed tests, and provides a URL to download the full test report.

Example usage  

# Test against development stage (default)
alexa-ai test

# Test against live stage
alexa-ai test --stage live

# Specific test suite file (MCP Toolkit)
alexa-ai test --test-suite test-suites/mcp-tests.json

# Filter tests by pattern (Category SDK only)
alexa-ai test --filter "booking.*cancel"

Example output  

Running tests against development stage...
  ⠋ Executing test suite (3 test cases)...

Test execution result: 2/3 passed, 1 failed
Add-on ID: amzn1.ask.addon.abc123

Example JSON output  

{
  "addOnId": "amzn1.ask.addon.abc123",
  "testExecutionId": "test-exec-abc123",
  "stage": "development",
  "status": "COMPLETED",
  "summary": {
    "totalTests": 3,
    "passed": 2,
    "failed": 1
  },
  "reportUrl": "https://s3.amazonaws.com/addon-test-reports/test-exec-abc123.json",
  "reportHtmlUrl": "https://s3.amazonaws.com/addon-test-reports/test-exec-abc123.html",
  "expiresAt": "2026-03-30T10:00:00Z"
}

alexa-ai submit

Submits the current development version of the add-on for certification.

alexa-ai submit [--yes] [--json]

Flow

1. Resolves the add-on ID from .alexa-ai/config.json.
2. Prompts for confirmation (skipped if --yes is provided).
3. Calls POST /v1/addons/{addOnId}/submit. Returns SUBMITTED_FOR_CERTIFICATION status.
4. The certification workflow validates artifacts and initiates the review process.

Example usage  

# Interactive — prompts for confirmation
alexa-ai submit

# Non-interactive (CI/CD)
alexa-ai submit --yes

Example output  

Submitting add-on for certification...
  Add-on:   Example Travel (amzn1.ask.addon.abc123)
  Version: 3

Are you sure you want to submit for certification? (y/N): y

✓ Add-on submitted for certification.
  Status: SUBMITTED_FOR_CERTIFICATION

Example JSON output  

{
  "addOnId": "amzn1.ask.addon.abc123",
  "version": 3,
  "status": "SUBMITTED_FOR_CERTIFICATION"
}

alexa-ai list

Lists all add-ons owned by the authenticated vendor.

alexa-ai list [--max-results <n>] [--next-token <token>] [--json]

Flow

1. Resolves the vendor ID from the authentication token.
2. Calls GET /v1/addons?vendorId={vendorId}&maxResults={n}&nextToken={token}&sortBy={field}&sortOrder={order}. Returns a paginated list of add-ons.
3. Each entry includes the add-on ID, name, latest version, stage, status, and last updated timestamp.
4. If a nextToken is present in the response, use --next-token to retrieve the next page.

Example usage  

# List all add-ons (default: up to 10)
alexa-ai list

# Custom page size
alexa-ai list --max-results 25

Example output  

Your add-ons:

  Name                Add-on ID                     Latest   Stage            Status                       Last Updated
  Example Travel      amzn1.ask.addon.abc123        4        development      DEPLOYED                     2026-03-29 10:00 UTC
  Example Rides       amzn1.ask.addon.ghi789        2        live             PUBLISHED                    2026-03-26 09:00 UTC
  Example Dining      amzn1.ask.addon.def456        3        certification    CERTIFICATION_IN_PROGRESS    2026-03-27 12:00 UTC

Example JSON output  

{
  "addOns": [
    {
      "addOnId": "amzn1.ask.addon.abc123",
      "name": "Example Travel",
      "stage": "development",
      "lastUpdated": "2026-03-29T10:00:00Z"
    }
  ],
  "totalCount": 1,
  "nextToken": null
}

alexa-ai status

Checks the lifecycle status of an add-on or a specific deployment.

alexa-ai status [--addon-id <id>] [--deployment-id <id>] [--json]

Example usage  

# Check status of current add-on
alexa-ai status

# Check status of a specific add-on
alexa-ai status --addon-id amzn1.ask.addon.abc123

# Check a specific deployment
alexa-ai status --addon-id amzn1.ask.addon.abc123 --deployment-id deploy-xyz789

alexa-ai configure-account-linking

Configures OAuth2 account linking for an add-on. Account linking enables your add-on to access user data from your service by connecting the user's Alexa identity to their account on your service.

alexa-ai configure-account-linking --addon-id <id> --config-file <path> [--json]

Example usage  

# Configure account linking from a config file
alexa-ai configure-account-linking --addon-id amzn1.ask.addon.abc123 --config-file ./account-linking-config.json

alexa-ai get-account-linking

Retrieves the current OAuth2 account linking configuration for an add-on.

alexa-ai get-account-linking [--addon-id <id>] [--stage <stage>] [--json]

Example usage  

# Get account linking config for current add-on (development stage)
alexa-ai get-account-linking

# Get account linking config for a specific stage
alexa-ai get-account-linking --addon-id amzn1.ask.addon.abc123 --stage live

Catalog commands

Use these commands to manage point of interest (POI) and event data catalogs.

alexa-ai create-catalog

Creates a new catalog for a vendor.

alexa-ai create-catalog --title <title> --type <type> --usage <usage> [--json]

alexa-ai upload-catalog

Uploads data to an existing catalog.

alexa-ai upload-catalog --catalog-id <id> --file <path> [--json]

alexa-ai associate-catalog-with-addon

Associates a catalog with an add-on.

alexa-ai associate-catalog-with-addon --addon-id <id> --catalog-id <id>

alexa-ai get-content-upload-by-id

Gets the processing status of a catalog content upload.

alexa-ai get-content-upload-by-id --catalog-id <id> --upload-id <id> [--json]

alexa-ai list-catalogs

Lists catalogs owned by the authenticated vendor.

alexa-ai list-catalogs [--max-results <n>] [--next-token <token>] [--json]

alexa-ai get-catalog

Gets details of a specific catalog.

alexa-ai get-catalog --catalog-id <id> [--json]

alexa-ai list-catalog-uploads

Lists content uploads for a specific catalog.

alexa-ai list-catalog-uploads --catalog-id <id> [--max-results <n>] [--next-token <token>] [--json]

Add-on usage metrics commands

Use these commands to discover and query usage metrics for your add-on, including task completion funnels, engagement, account linking, and API performance data.

Metric families

Metrics are organized into families:

Category-level families require the --category flag for add-ons with multiple categories. For single-category add-ons, the category is resolved automatically.

Supported stats:

Supported aggregation periods:

For the full list of available metric names, supported stats, and dimensions, see Add-on Metrics Catalog.

alexa-ai list-addon-metrics

Discovers available metrics for your add-on. Use this command to find metric names, supported stats, and available dimensions before running a query.

alexa-ai list-addon-metrics \
    --addon-id <addon-id> \
    [--stage <stage>] \
    [--family <family>] \
    [--category <category>] \
    [--max-results <number>] \
    [--next-token <token>]

Example usage  

# List all available metrics for your add-on
alexa-ai list-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon

# List task completion metrics for a specific category
alexa-ai list-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --family TaskCompletion \
    --category FoodOrdering

Example JSON response  

{
  "metrics": [
    {
      "name": "RESTAURANTS_SEARCH",
      "label": "Customer searched restaurants",
      "family": "TaskCompletion",
      "category": "FoodOrdering",
      "stepNumber": 1.0,
      "unit": "COUNT",
      "supportedDimensions": ["AlexaAI.Locale", "AlexaAI.Country"],
      "supportedGroupByOptions": [],
      "supportedStats": ["UNIQUE_COUNT", "COUNT"],
      "supportedAggregationPeriods": ["P1D", "P1W", "P1M"]
    }
  ],
  "paginationContext": {
    "totalCount": 12,
    "nextToken": "eyJ..."
  }
}

alexa-ai get-addon-metrics

Retrieves time series metric data for your add-on. You can query a single metric, compare up to five metrics side by side, or expand an entire family to get the full funnel in one call.

alexa-ai get-addon-metrics \
    --addon-id <addon-id> \
    --period <aggregation-period> \
    [--stage <stage>] \
    [--metric <metric-name>] \
    [--family <family>] \
    [--category <category>] \
    [--stat <stat>] \
    [--start-time <ISO-8601>] \
    [--end-time <ISO-8601>] \
    [--last-n-periods <number>] \
    [--group-by <dimension>] \
    [--country <code>] \
    [--locale <locale>] \
    [--queries '<JSON>']

Time range rules: Specify a time range using one of these mutually exclusive options:

• --last-n-periods—returns the last N aggregation buckets. If you omit all time range options, this defaults to 3.
• --start-time and --end-time—explicit ISO-8601 range.

Providing both returns a 400 INVALID_REQUEST error.

Example usage  

# Single metric — daily unique customers over last 7 days
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --last-n-periods 7 \
    --period P1D \
    --metric RESTAURANTS_SEARCH \
    --category FoodOrdering \
    --stat UNIQUE_COUNT

# Explicit time range
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --start-time 2026-05-15T00:00:00Z \
    --end-time 2026-05-22T00:00:00Z \
    --period P1D \
    --metric RESTAURANTS_SEARCH \
    --category FoodOrdering \
    --stat UNIQUE_COUNT

# Full task completion funnel (omit --metric, specify --family)
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --start-time 2026-05-15T00:00:00Z \
    --end-time 2026-05-22T00:00:00Z \
    --period P1D \
    --family TaskCompletion \
    --category FoodOrdering \
    --stat UNIQUE_COUNT

# Add-on-level metric (no category needed)
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --last-n-periods 7 \
    --period P1D \
    --metric ACCOUNT_LINKING_COMPLETED \
    --stat UNIQUE_COUNT

# Multi-metric comparison (up to 5)
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --last-n-periods 7 \
    --period P1D \
    --stat UNIQUE_COUNT \
    --category FoodOrdering \
    --queries '[
      {"id": "m1", "name": "RESTAURANTS_SEARCH"},
      {"id": "m2", "name": "ORDER_INITIATED"},
      {"id": "m3", "name": "ORDER_PLACED"},
      {"id": "m4", "name": "ORDER_COMPLETED"},
      {"id": "m5", "name": "PAYMENT_CONFIRMED"}
    ]'

# Performance monitoring with error breakdown
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --start-time 2026-05-15T00:00:00Z \
    --end-time 2026-05-22T00:00:00Z \
    --period P1D \
    --metric API_ERROR_COUNT \
    --category FoodOrdering \
    --stat COUNT \
    --group-by AlexaAI.ErrorCode

# Filter by country
alexa-ai get-addon-metrics \
    --addon-id amzn1.ask.addon.myaddon \
    --last-n-periods 7 \
    --period P1D \
    --metric RESTAURANTS_SEARCH \
    --category FoodOrdering \
    --stat UNIQUE_COUNT \
    --country US

Example JSON response  

{
  "results": [
    {
      "id": "m1",
      "label": "Unique customers who searched restaurants",
      "family": "TaskCompletion",
      "category": "FoodOrdering",
      "name": "RESTAURANTS_SEARCH",
      "unit": "COUNT",
      "stat": "UNIQUE_COUNT",
      "aggregationPeriod": "P1D",
      "data": [
        {
          "timestamps": ["2026-05-15T00:00:00Z", "2026-05-16T00:00:00Z", "2026-05-17T00:00:00Z"],
          "values": [142, 187, 203]
        }
      ]
    }
  ],
  "paginationContext": {
    "nextToken": null
  }
}

When --group-by is set, the data array contains multiple entries—one per distinct value of the grouped field, sorted by volume in descending order.

Metrics error codes

The following errors are specific to the metrics commands. For general errors that apply to all commands (authentication, rate limiting, server errors), see Error codes.

Error codes

When a command fails, the CLI displays errors in the following format:

Human-readable (default):

[<ERROR_CODE>] <description>.
  Fix: <command>

Examples  

[UNAUTHORIZED] Authentication failed - your credentials have expired or are invalid.
  Fix: alexa-ai configure

[ADDON_NOT_FOUND] Add-on amzn1.ask.addon.abc123 does not exist.

[TOO_MANY_REQUESTS] Rate limit exceeded.

JSON error format (with –json flag)  

{
  "success": false,
  "command": "deploy",
  "errorCode": "INVALID_REQUEST",
  "error": "Package build failed.
[VALIDATION_ERROR] policy url not present",
  "fix": "alexa-ai deploy",
  "data": {
    "addOnId": "amzn1.ask.addon.abc123",
    "stage": "development",
    "packageHash": "sha256:a1b2c3d4..."
  }
}

Common error codes

Related topics

• Build Alexa+ Add-ons: Development Stages
• Alexa+ Add-ons

Last updated: Aug 18, 2026