Alexa Skills Kit Command Line Interface (ASK CLI) Overview

The Alexa Skills Kit Command Line Interface (ASK CLI) helps you perform most Alexa skills tasks from the command line. Use the ASK CLI to:

  • Create new skills
  • Update and build your skill's interaction model
  • Deploy your skill to Alexa-hosted skills or AWS
  • Simulate your skill
  • Submit your skill for certification and publishing

To download and install the ASK CLI, see ASK CLI Quick Start.

Create a new skill project

To create a new skill, run ask new, which prompts you to choose a language runtime for your skill:

$ ask new
? Choose the programming language you will use to code your skill
  - NodeJS
  - Python
  - Java

Next, choose the hosting provider for the backend code for your skill. The ASK CLI supports deployment to the following hosting providers:

Hosting Provider                          Description
Alexa-hosted skills Creates a new skill in your account and provides free hosting for your skill, including an AWS Lambda function to run your skill code, an AWS S3 bucket for media storage, and an AWS CodeCommit repository.
AWS with CloudFormation Requires AWS Account. Creates a new skill project that includes a starter AWS CloudFormation template. ASK CLI utilizes this template to provision the AWS resources required to host your skill, including a Lambda function and a S3 bucket.
AWS Lambda Requires AWS Account. Creates a new skill project that will have its skill code deployed directly to an AWS Lambda function.

You can also choose to manage your own hosting for your skill. We recommend using Alexa-hosted skills if you don't already have an AWS account.

? Choose a method to host your skill's backend code
- Alexa-Hosted
Host your skill code with Alexa (free)
- AWS with CloudFormation
Host your skill code with AWS and provision with CloudFormation (requires AWS account)
- AWS Lambda
Host your skill code on AWS Lambda (requires AWS account)
- Self-Hosted
Manage your own hosting

Based on your hosting selection, you might have to choose a starter template for your skill:

? Choose a template to start with
- Hello world		  Alexa's hello world skill to send the greetings to the world!
- Fact skill		  Quick sample skill to manage a collection of voice data.
- High low game		Guess a number high or low using persistent attributes.

Finally, provide a name for your skill and the local project name:

? Please type in your skill name:  My skill
? Please type in your folder name for the skill project (alphanumeric):  my-skill-project

The command creates your new skill project in your current directory.

You can also create a new skill by using your own custom skill templates. To use a custom template, provide the Git URL of the template with --template-url:

$ ask new --template-url https://example.com/example/example-skill.git

Skill project structure

By default, when you create a project with the ASK CLI using an Alexa skills template, the project contains the following:

Project file or folder                         Purpose
skill-package/ Contains the Skill Package resources such as the skill's manifest and any associated interaction models, in-skill products, and image assets.
infrastructure/ The CloudFormation template for a skill will reside in this folder if deploying with AWS CloudFormation.
lambda/ Contains the skill's backend source code.
ask-resources.json JSON configuration file utilized by ASK CLI for skill deployment.

Test your skill locally

While you are building your skill, you can start a debugging session to test your skill locally as described following. Requests to your skill are routed to your local computer instead of your Lambda function. If your skill is already deployed, see Test your skill instead.

Prepare to test your local Alexa skill

Before you can invoke your local skill, add ask-sdk-local-debug to your skill project.

To prepare to test your local Alexa skill

  1. Open a command window.
  2. Change to the lambda folder of your skill project.
  3. Run npm install --save-dev ask-sdk-local-debug.

Test your local Alexa skill

To test your local Alexa skill

  1. Open a command window and change to the root folder of your skill project.
  2. Use the ask run command to start a debugging session.
  3. Use the ask dialog to send requests to your skill locally.

Deploy your skill

Deploy to AWS Lambda

To deploy a skill configured for AWS Lambda, run the ask deploy command.

$ ask deploy

The ASK CLI performs the following actions to deploy your skill:

  1. Package and upload the contents of the skill's skill-package/ directory to Alexa Skills using the Skill Package API. If this is the first time that you've deployed the skill, the command creates a new skill in the configured Amazon developer account.
  2. Build the skill code under the lambda/ directory and package the build artifacts for deployment to AWS. This includes installing the skill's dependencies and producing any build artifacts. For a skill written for Node.js, this means running npm install to install dependencies declared in package.json and packaging it with the JavaScript source code.
  3. Deploy build artifacts to the configured AWS Lambda function. If this is the first time the skill has been deployed and a Lambda ARN has not been configured, the command creates a new Lambda function.

Deploy Alexa-hosted skills with Git

If you created an Alexa-hosted skill, deploy your skill by using Git.

Run the git push command to push code from the repository on your local computer to the remote repository with Alexa-hosted skills, typically origin:

$ git push origin master

Use this command when you want to deploy the latest committed version of your skill to an Alexa-hosted skill. After you push your changes, the Alexa-hosted skill deploys both your skill package resources and the backend skill code from the remote repository. An Alexa-hosted skill only deploys code that you push to the remote branch named master.

Deploy with AWS CloudFormation

By default, skills configured for CloudFormation deployment include a starter CloudFormation template named skill-stack.yaml under the infrastructure/ directory of the skill project. Update this CloudFormation template to add AWS resources to your skill. For more information about CloudFormation, see Getting Started with CloudFormation.

When you are ready to deploy your skill, run:

$ ask deploy

ASK CLI performs the following actions to deploy your skill:

  1. Package and upload the contents of the skill's skill-package/ directory to Alexa Skills using the Skill Package API. If this is the first time that you've deployed the skill, the command creates a new skill under the configured Amazon developer account.
  2. Build the skill code under the lambda/ directory and package the build artifacts for deployment to AWS. This includes installing the skill's dependencies and producing any build artifacts. For a skill written for Node.js, this means running npm install to install dependencies declared in package.json and packaging it with the JavaScript source code.
  3. Upload the build artifacts along with the CloudFormation template found under the infrastructure/ directory (by default, this template file is named skill-stack.yaml) to an S3 bucket created under the configured AWS account.
  4. Invoke AWS CloudFormation to provision the AWS resources defined in the uploaded CloudFormation template, which also deploys the uploaded build artifacts in S3 to the provisioned Lambda function.

How to keep build artifacts out of Git

When deploying to AWS, ASK CLI produces build artifacts under the .ask/ directory. To exclude these artifacts from Git, add .ask/ to the skill project's .gitignore.

Test your skill

If your skill is already deployed, use the ask dialog command to send requests to your deployed skill as described following. If your skill isn't deployed, see Test your skill locally instead.

To test your skill from command line, run ask dialog and specify a locale supported by your skill:

$ ask dialog --locale en-US

The command opens an interactive terminal and you can simulate a multi-turn conversation with Alexa. For example:

============================== Welcome to ASK Dialog ===============================
=== In interactive mode, type your utterance text onto the console and hit enter ===
============= Alexa will then evaluate your input and give a response! =============

User  > open hello world
Alexa > Welcome, you can say Hello or Help. Which would you like to try?
User  > help
Alexa > You can say hello to me! How can I help?
User  > hello
Alexa > Hello World!
User  > .record <path_to_replay_file>
Created replay file at <path_to_replay_file>
User  > .quit

================================= Goodbye! =========================================

Manage skill resources with SMAPI

When you manage Alexa skills with ASK CLI or SMAPI, use the corresponding JSON schema for a given skill resources. For more information, see:

Team development best practices

Accounts management

ASK CLI uses the Authorization Code grant approach following the OAuth 2.0 standard. ASK CLI is a client-side tool, so it's your responsibility to ensure the security of the refresh token used to retrieve the access token. Good security practice requires additional caution when a skill is being developed by a team, as leakage of the refresh token can happen more easily, particularly if the team shares the same team account.

We recommend that the team leader who owns the vendor owner account also have an unshared customer account. The access for other developers, each of whom should also use their own customer accounts, is managed by memberships to the vendor. This approach strictly defines the permissions within your team and voids the refresh token when a release occurs.

For more information about managing a single account with multiple users, see Manage Your Amazon Developer Account and Permissions.

Compromised accounts

If you suspect your account has been compromised, follow the solution based on your situation below.

If you need to:

  • Revoke all refresh tokens: Open Your Account > Manage Login with Amazon and remove your application. Removing your application invalidates the refresh tokens that your team stored in ASK CLI. The non-expired access token continues to work. Next time you authenticate through Login with Amazon, Login with Amazon prompts you to grant the scopes again and creates the ASK CLI application again.

  • Reset password for your Amazon account: After you reset your password, follow the instructions for revoking all refresh tokens to invalidate the refresh tokens stored in ASK CLI.

Last updated: Jun 03, 2022