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.

Parameter	Short	Type	Required	Default	Description
`--profile`	`-p`	String	No	`default`	Named credential profile to use. Create profiles with `alexa-ai configure --profile <name>`.
`--debug`	—	Flag	No	—	Enables verbose debug output including HTTP request and response details.
`--help`	`-h`	Flag	No	—	Prints the description and available options for the command.

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]

Parameter	Type	Required	Description
`--profile`	String	No	Named profile for storing credentials.
`--no-browser`	Flag	No	Prints the auth URL instead of opening a browser. Use in SSH environments.

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

Argument	Type	Required	Description
`type`	String	No	Integration type to scaffold. Values: `mcp`, `action`. If omitted, the CLI prompts you to choose.

Options

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

Parameter	Type	Applies to	Description
`--name`	String	Category SDK and MCP Toolkit	Add-on display name.
`--locale`	String	Category SDK and MCP Toolkit	Locale for the add-on. Default: `en-US`.
`--mcp-server-url`	String	MCP Toolkit only	MCP server endpoint URL.
`--category`	String	Category SDK and MCP Toolkit	Category for the add-on. Category SDK values: `restaurant-reservation`, `food-ordering`, `home-services`, `local-booking`, `ticketing`. MCP Toolkit values (in-category add-ons only): `ride_booking`.
`--language`	String	Category SDK only	Programming language. Values: `typescript`.
`--hosting`	String	Category SDK only	Hosting method. Values: `cdk`.
`--non-interactive`	Flag	Category SDK and MCP Toolkit	Skip all interactive prompts. Requires all mandatory options to be provided on the command line.
`--requires-auth`	Flag	MCP Toolkit only	Indicates the MCP server requires authentication.
`--auth-client-id`	String	MCP Toolkit only	OAuth2 client ID for MCP server authentication.
`--auth-scopes`	String	MCP Toolkit only	Space-separated list of OAuth2 scopes required by the MCP server.

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]

Parameter	Type	Required	Description
`--ignore-hash`	Flag	No	Force deploy even if no changes detected.
`--skip-validation`	Flag	No	Skip pre-deploy validation checks.
`--json`	Flag	No	Outputs results in JSON format.

Flow

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.
Zips the addon-package/ directory and calls POST /v1/addons/uploads to get a pre-signed S3 upload URL.
Uploads the ZIP to the pre-signed URL.
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.
Polls GET /v1/addons/{addOnId}/packages/{packageId} until the build reaches a terminal state (BUILT or FAILED).
Calls POST /v1/addons/{addOnId}/deployments with the packageId to deploy to the development stage. Returns a deploymentId via the Location response header.
Polls GET /v1/addons/{addOnId}/deployments/{deploymentId} until deployment reaches a terminal state (SUCCEEDED or FAILED).
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:

Status	Description
`SUCCEEDED`	Build and deployment completed.
`BUILD_IN_PROGRESS`	Package build is still running.
`BUILD_FAILED`	Package build failed. See `status.failureReason` for details.
`DEPLOY_IN_PROGRESS`	Build succeeded, deployment to stage is still running.
`DEPLOY_FAILED`	Deployment to stage failed. See `status.failureReason` for details.

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]

Parameter	Type	Required	Default	Description
`--stage`	String	No	`development`	Stage to test against. Values: `development`, `live`.
`--test-suite`	String	No	`test-suites/`	Path to a test suite JSON file or directory.
`--filter`	String	No	—	Regex pattern to filter which tests to run. Only applicable for Category SDK add-ons.
`--profile`	String	No	`default`	Named credential profile to use.
`--json`	Flag	No	—	Outputs results in JSON format.

Flow

Reads the test suite from the local test-suites/ directory or the path specified by --test-suite.
Calls POST /v1/addons/{addOnId}/stages/{stage}/tests with the test suite. Returns a testExecutionId.
Polls GET /v1/addons/{addOnId}/tests/{testExecutionId} until the execution reaches a terminal state (COMPLETED or SYSTEM_ERROR).
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]

Parameter	Type	Required	Description
`--yes`	Flag	No	Skips the interactive confirmation prompt.
`--json`	Flag	No	Outputs results in JSON format.

Flow

Resolves the add-on ID from .alexa-ai/config.json.
Prompts for confirmation (skipped if --yes is provided).
Calls POST /v1/addons/{addOnId}/submit. Returns SUBMITTED_FOR_CERTIFICATION status.
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]

Parameter	Type	Required	Default	Description
`--max-results`	Integer	No	`10`	Maximum number of add-ons to return. Maximum value is 50.
`--next-token`	String	No	—	Pagination token from a previous response.
`--json`	Flag	No	—	Outputs results in JSON format.

Flow

Resolves the vendor ID from the authentication token.
Calls GET /v1/addons?vendorId={vendorId}&maxResults={n}&nextToken={token}&sortBy={field}&sortOrder={order}. Returns a paginated list of add-ons.
Each entry includes the add-on ID, name, latest version, stage, status, and last updated timestamp.
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]

Parameter	Type	Required	Description
`--addon-id`	String	No	Add-on identifier. If not provided, resolves from `.alexa-ai/config.json`.
`--deployment-id`	String	No	Deployment identifier to check status of a specific deployment.
`--json`	Flag	No	Outputs results in JSON format.

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]

Parameter	Type	Required	Description
`--addon-id`	String	Yes	Add-on identifier.
`--config-file`	String	Yes	Path to a JSON file containing the OAuth2 account linking configuration.
`--json`	Flag	No	Outputs results in JSON format.

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]

Parameter	Type	Required	Default	Description
`--addon-id`	String	No	—	Add-on identifier. If not provided, resolves from `.alexa-ai/config.json`.
`--stage`	String	No	`development`	Stage to retrieve the configuration from. Values: `development`, `certification`, `certified`, `live`.
`--json`	Flag	No	—	Outputs results in JSON format.

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]

Parameter	Type	Required	Description
`--title`	String	Yes	Human-readable name for the catalog.
`--type`	String	Yes	Catalog type (for example, `AMAZON.BroadcastChannel`).
`--usage`	String	Yes	The catalog’s usage (for example, `AlexaMusic.Catalog.BroadcastChannel`).
`--json`	Flag	No	Outputs results in JSON format.

alexa-ai upload-catalog

Uploads data to an existing catalog.

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

Parameter	Type	Required	Description
`--catalog-id`	String	Yes	Catalog identifier from `create-catalog`.
`--file`	String	Yes	Path to the data file (JSON) to upload.
`--json`	Flag	No	Outputs results in JSON format.

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>

Parameter	Type	Required	Description
`--addon-id`	String	Yes	Add-on identifier.
`--catalog-id`	String	Yes	Catalog identifier to associate.

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]

Parameter	Type	Required	Description
`--catalog-id`	String	Yes	Catalog identifier.
`--upload-id`	String	Yes	Upload identifier from `upload-catalog`.
`--json`	Flag	No	Outputs results in JSON format.

alexa-ai list-catalogs

Lists catalogs owned by the authenticated vendor.

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

Parameter	Type	Required	Default	Description
`--max-results`	Integer	No	`10`	Maximum number of catalogs to return.
`--next-token`	String	No	—	Pagination token from a previous response.
`--json`	Flag	No	—	Outputs results in JSON format.

alexa-ai get-catalog

Gets details of a specific catalog.

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

Parameter	Type	Required	Description
`--catalog-id`	String	Yes	Catalog identifier.
`--json`	Flag	No	Outputs results in JSON format.

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]

Parameter	Type	Required	Default	Description
`--catalog-id`	String	Yes	—	Catalog identifier.
`--max-results`	Integer	No	`10`	Maximum number of uploads to return.
`--next-token`	String	No	—	Pagination token from a previous response.
`--json`	Flag	No	—	Outputs results in JSON format.

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:

Family	Description	Scope
`AccountLinking`	Account linking completion and drop-off metrics	Add-on level (no category needed)
`Permission`	Permission grant and revoke metrics	Add-on level (no category needed)
`Engagement`	Customer engagement and discovery metrics	Category level
`TaskCompletion`	End-to-end task completion funnel steps	Category level
`Performance`	API latency and error rate metrics	Category level

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:

Stat	Description
`UNIQUE_COUNT`	Number of unique customers
`COUNT`	Total number of requests or events
`AVERAGE`	Mean value
`RATE`	Ratio or percentage
`TM99`	Trimmed mean 99—average of values below the 99th percentile
`TM90_99`	Trimmed mean 90:99—average of values between the 90th and 99th percentile

Supported aggregation periods:

Period	Description
`P1D`	Daily
`P1W`	Weekly
`P1M`	Monthly

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>]

Parameter	Type	Required	Description
`--addon-id`	String	Yes	Your add-on identifier (for example, `amzn1.ask.addon.myaddon`).
`--stage`	String	No	Add-on deployment stage: `development`, `certification`, `certified`, or `live`. Default: `live`.
`--family`	String	No	Filter by metric family: `AccountLinking`, `Permission`, `Engagement`, `TaskCompletion`, or `Performance`.
`--category`	String	No	Filter by category (for example, `FoodOrdering`). PascalCase.
`--max-results`	Integer	No	Maximum metrics to return per page (1–100). Default: 10.
`--next-token`	String	No	Pagination token from a previous response.

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>']

Parameter	Type	Required	Description
`--addon-id`	String	Yes	Your add-on identifier.
`--period`	String	Yes	Aggregation period: `P1D`, `P1W`, or `P1M`.
`--stage`	String	No	Add-on deployment stage: `development`, `certification`, `certified`, or `live`. Default: `live`.
`--metric`	String	Conditional	Metric name (for example, `RESTAURANTS_SEARCH`). Required unless `--family` is provided.
`--family`	String	Conditional	Metric family. Required when `--metric` is omitted (family expansion mode).
`--category`	String	No	Category filter (for example, `FoodOrdering`). Required for multi-category add-ons when querying category-level families.
`--stat`	String	Conditional	Aggregation stat: `COUNT`, `UNIQUE_COUNT`, `AVERAGE`, `RATE`, `TM99`, or `TM90_99`. Required when `--metric` is provided.
`--start-time`	String	No	Start of time range in ISO-8601 format (for example, `2026-05-15T00:00:00Z`). Mutually exclusive with `--last-n-periods`.
`--end-time`	String	No	End of time range in ISO-8601 format. Required if `--start-time` is provided.
`--last-n-periods`	Integer	No	Number of recent periods to return. Default: 3. Max depends on period (7 for `P1D`, 12 for `P1W`, 13 for `P1M`). Mutually exclusive with `--start-time`/`--end-time`.
`--group-by`	String	No	Breakdown dimension: `AlexaAI.ErrorCode` or `AlexaAI.ApiInvoked` (Performance family only).
`--country`	String	No	Filter by country code (for example, `US`).
`--locale`	String	No	Filter by locale (for example, `en-US`).
`--queries`	JSON	No	JSON array of up to five metric queries for multi-metric comparison. Each query can override `--stat`, `--category`, and `--group-by`.

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.

HTTP status	Error code	Cause
400	`INVALID_REQUEST`	Missing required field, mutually exclusive time options used together, or `lastNPeriods` exceeds max for the period.
400	`TOO_MANY_QUERIES`	More than five queries provided.
400	`CATEGORY_REQUIRED`	Multi-category add-on without a `--category` value for a category-level family.
400	`STAT_MISMATCH`	Requested stat isn’t supported for the specified metric.
400	`UNSUPPORTED_AGGREGATION_PERIOD`	The requested aggregation period isn’t available.
400	`TIME_RANGE_EXCEEDED`	Time range exceeds the allowed window for the aggregation period.
400	`DIMENSION_NOT_APPLICABLE`	Dimension (for example, `AlexaAI.ApiInvoked`) isn’t supported for the metric’s family.
404	`NOT_FOUND`	Unknown metric name or family.

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

Field	Type	Description
`success`	Boolean	Always `false`.
`command`	String	Which command failed.
`errorCode`	String or null	Error code from AAPI (for example, `UNAUTHORIZED`, `ADDON_NOT_FOUND`).
`error`	String	Human-readable error description.
`fix`	String or null	Runnable CLI command to resolve the issue, or `null`.
`data`	Object or null	Partial context from the failed operation (for example, `addOnId`, `stage`).

Common error codes

HTTP status	Code	Description
400	`INVALID_REQUEST`	Malformed request body or missing required fields.
400	`INVALID_STAGE`	Invalid stage value. Must be `development` or `live`.
401	`NOT_AUTHENTICATED`	The request has a missing, invalid, or expired authentication token.
403	`NOT_AUTHORIZED`	The caller is authenticated but doesn’t have permission to perform this operation.
404	`ADDON_NOT_FOUND`	Add-on with the specified ID doesn’t exist.
404	`PACKAGE_NOT_FOUND`	Package with the specified ID doesn’t exist.
404	`DEPLOYMENT_NOT_FOUND`	Deployment with the specified ID doesn’t exist.
404	`CATALOG_NOT_FOUND`	Catalog with the specified ID doesn’t exist.
404	`TEST_EXECUTION_NOT_FOUND`	Test execution with the specified ID doesn’t exist.
409	`CONFLICT`	Operation conflicts with current state. For example, another version is already in certification.
409	`INVALID_LIFECYCLE_STATE`	Add-on isn’t in the required lifecycle state for this operation.
429	`TOO_MANY_REQUESTS`	Rate limit exceeded. Retry after the number of seconds indicated in the `Retry-After` response header.
500	`INTERNAL_SERVER_ERROR`	Unexpected server error.

Get Started

Build with the MCP Toolkit

Build with the Category SDK

Testing

Certification

Reference

Overview

Common parameters

alexa-ai configure

alexa-ai new

Positional argument

Options

Interactive mode

Non-interactive mode

alexa-ai deploy

alexa-ai test

alexa-ai submit

alexa-ai list

alexa-ai status

alexa-ai configure-account-linking

alexa-ai get-account-linking

Catalog commands

alexa-ai create-catalog

alexa-ai upload-catalog

alexa-ai associate-catalog-with-addon

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

alexa-ai list-catalogs

alexa-ai get-catalog

alexa-ai list-catalog-uploads

Add-on usage metrics commands

alexa-ai list-addon-metrics

alexa-ai get-addon-metrics

Metrics error codes

Error codes

Common error codes

​Overview

​Common parameters

​alexa-ai configure

​alexa-ai new

​Positional argument

​Options

​Interactive mode

​Non-interactive mode

​alexa-ai deploy

​alexa-ai test

​alexa-ai submit

​alexa-ai list

​alexa-ai status

​alexa-ai configure-account-linking

​alexa-ai get-account-linking

​Catalog commands

​alexa-ai create-catalog

​alexa-ai upload-catalog

​alexa-ai associate-catalog-with-addon

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

​alexa-ai list-catalogs

​alexa-ai get-catalog

​alexa-ai list-catalog-uploads

​Add-on usage metrics commands

​alexa-ai list-addon-metrics

​alexa-ai get-addon-metrics

​Metrics error codes

​Error codes

​Common error codes

​Related topics

Overview

Common parameters

alexa-ai configure

alexa-ai new

Positional argument

Options

Interactive mode

Non-interactive mode

alexa-ai deploy

alexa-ai test

alexa-ai submit

alexa-ai list

alexa-ai status

alexa-ai configure-account-linking

alexa-ai get-account-linking

Catalog commands

alexa-ai create-catalog

alexa-ai upload-catalog

alexa-ai associate-catalog-with-addon

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

alexa-ai list-catalogs

alexa-ai get-catalog

alexa-ai list-catalog-uploads

Add-on usage metrics commands

alexa-ai list-addon-metrics

alexa-ai get-addon-metrics

Metrics error codes

Error codes

Common error codes

Related topics