Alexa Skills Kit Command Line Interface (ASK CLI) Overview

Note: Sign in to the developer console to build or publish your skill.

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 perform the following tasks:

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 Quick Start: Alexa Skills Kit Command Line Interface.

Important: By default, the ASK CLI transmits telemetry data in the background. Telemetry is the automated collection of usage statistics, systems data, and error logs. This information is helpful in diagnosing issues, improving features, and developing new products and services. You can opt out of telemetry at any time. For details, see Opt Out of ASK CLI Telemetry.

Skill project structure
Steps to create, test, and deploy a new skill by using the ASK CLI
Team development best practices
Related topics

Skill project structure

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

skill-package/ – Contains the skill package resources such as your skill's manifest and any associated interaction models, in-skill products, and image assets.
infrastructure/ – Contains an AWS CloudFormation template for your skill, if you choose AWS CloudFormation as your deployment method.
lambda/ – Contains your skill's back-end source code in AWS Lambda.
ask-resources.json – Provides a JSON configuration that the ASK CLI uses for skill deployment.

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

Steps to create, test, and deploy a new skill by using the ASK CLI

To create, test, and deploy a new skill by using the ASK CLI, perform the following steps.

Create a new skill.
Test your skill locally.
Deploy your skill.
Test your deployed skill.
Manage skill resources with SMAPI.

Step 1: Create a new skill

To create a new skill by using the ASK CLI, perform the following steps.

To create a new skill

On a command line, run the ask new command, which prompts you to choose a modeling stack for your skill. Choose one of the following options:
- Interaction model – The Interaction Model stack enables you to define the user interactions with a combination of utterances, intents, and slots.
- Alexa Conversations – Alexa Conversations uses deep learning to manage the dialog flow. User utterances, Alexa Presentation Language (APL), and APL for audio (APLA) documents train the skill model to create natural, human-like Alexa voice experiences.
Note: If you choose Alexa Conversations as your modeling stack, you must compile your Alexa Conversations skill artifacts before you deploy your skill. For details, see Set up the ASK CLI to Use Alexa Conversations Description Language.
```
$ ask new
Choose a modeling stack for your skill: (Use arrow keys)
- Interaction Model
The Interaction Model stack enables you to define the user interactions with a combination of utterances, intents, and slots.
- Alexa Conversations
Alexa Conversations (AC) uses deep learning to manage the flow of dialog. User utterances and APL/APLA documents train the skill model to create natural, human-like Alexa voice experiences.
```

Choose a language runtime for your skill. You can choose between Node.js, Python, and Java.

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

Choose the hosting provider for the back-end code of your skill. The ASK CLI supports deployment to the following hosting providers:
- Alexa-hosted skills – (Recommended if you don't have an AWS account) Creates a new skill in your account and provides free hosting for your skill. This method creates an AWS Lambda function to run your skill code, an Amazon Simple Storage Service (S3) bucket for media storage, and an AWS CodeCommit repository.
- AWS with CloudFormation – (Requires an AWS account) Creates a new skill project that includes a starter AWS CloudFormation template. The ASK CLI uses this template to provision the AWS resources that your skill requires, including an AWS Lambda function and an Amazon S3 bucket.
- AWS Lambda – (Requires an AWS account) Creates a new skill project that will have its skill code deployed directly to an AWS Lambda function.
```
? Choose a method to host your skill's backend resources
       - Alexa-Hosted
Host your skill code by Alexa (free)
       - AWS with CloudFormation
Host your skill code with AWS and provision with AWS 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, choose a starter template for your skill, if applicable.

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

Provide a name for your skill and a name for the local project.
```
? Please type in your skill name:  My skill
? Please type in your folder name for the skill project (alphanumeric):  my-skill-project
```
The ask new 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. You can optionally use --template-branch to specify which branch to clone.
```
$ ask new --template-url https://example.com/example/example-skill.git --template-branch master-example-branch
```

Step 2: Test your skill locally

While you build your skill, you can start a debugging session to test your skill locally. Requests to your skill are routed to your local computer instead of to your Lambda function.

Note: If your skill is already deployed, see Test your deployed skill instead.

To test your skill locally for Node.js

Add ask-sdk-local-debug to your skill project by performing the following steps.
You must add ask-sdk-local-debug to your skill project before you can invoke your skill locally.
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.
In the command window, change to the root folder of your skill project.
Use the ask run command to start a debugging session.
Use the ask dialog command to send requests to your skill locally.

To test your skill locally for Python

Note: The steps below assume you already have virtualenv installed. If not, see Set up the SDK in a virtual envionment.

Add ask-sdk-local-debug to your skill project by performing the following steps.
You must add ask-sdk-local-debug to your skill project before you can invoke your skill locally.
1. Open a command window.
2. Change to the lambda folder of your skill project.
3. To create a virtual envionment, run python -m venv my-venv.
4. Activate the virtual envionment. If you are on Linux or MacOS, run source my-venv/bin/activate. If you are on Windows, run my-venv\Scripts\activate.
5. Run pip install ask-sdk-local-debug.
In the command window, change to the root folder of your skill project.
Use the ask run command to start a debugging session.
Use the ask dialog command to send requests to your skill locally.

Step 3: Deploy your skill

Depending on the method you chose to host your skill's back-end resources when you ran the ask new command, deploy your skill by using one of the following procedures:

Deploy your skill to AWS Lambda.
Deploy your Alexa-hosted skill by using Git.
Deploy your skill by using AWS CloudFormation.

Note: Skills created and managed with version 1.x of the ASK CLI must upgrade to the latest project format to deploy with version 2.x. For instructions on how to upgrade, see the CLI Migration Guide.

Deploy your skill to AWS Lambda

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

$ ask deploy

To deploy your skill, the ASK CLI performs the following actions:

Packages and uploads the contents of your skill's skill-package/ directory to Alexa by using the Skill Package API. If this is the first time that you've deployed your skill, the ask deploy command creates a new skill in the configured Amazon developer account.
Builds your skill code under the lambda/ directory and packages the build artifacts for deployment to AWS. This procedure installs your skill's dependencies and produces any build artifacts. For a Node.js skill, this procedure also runs npm install to install the dependencies that you declared in package.json and packages the dependencies with the JavaScript source code.
Deploys build artifacts to the configured AWS Lambda function. If this is the first time you've deployed your skill and an AWS Lambda ARN isn't configured, the ask deploy command creates a new Lambda function.

Deploy your Alexa-hosted skill by using Git

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

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

$ git push origin master

This command deploys 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 back-end skill code from the remote repository. An Alexa-hosted skill only deploys code that you push to the remote branch named master.

Deploy your skill by using AWS CloudFormation

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

When you're ready to deploy your skill, run the following command.

$ ask deploy

To deploy your skill, the ASK CLI performs the following actions:

Packages and uploads the contents of your skill's skill-package/ directory to Alexa by using the Skill Package API. If this is the first time that you've deployed your skill, the ask deploy command creates a new skill in the configured Amazon developer account.
Builds your skill code under the lambda/ directory and packages the build artifacts for deployment to AWS. This procedure installs your skill's dependencies and produces any build artifacts. For a Node.js skill, this procedure also runs npm install to install the dependencies that you declared in package.json and packages the dependencies with the JavaScript source code.
Uploads the build artifacts along with the AWS CloudFormation template, which is under the infrastructure/ directory, to an Amazon S3 bucket created under the configured AWS account. By default, this template file is named skill-stack.yaml.
Invokes AWS CloudFormation to provision the AWS resources defined in the uploaded AWS CloudFormation template. AWS CloudFormation also deploys the uploaded build artifacts in Amazon S3 to the provisioned AWS Lambda function.

Step 4: Test your deployed skill

If your skill is already deployed, run the ask dialog command to send requests to your deployed skill. When you run the ask dialog command, you must specify a locale.

Note: If your skill isn't deployed, see Test your skill locally instead.

$ ask dialog --locale en-US

The ask dialog command opens an interactive terminal. You can use this terminal to simulate a multi-turn conversation with Alexa. The following example shows a multi-turn conversation in the terminal.

============================== 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! =========================================

Step 5: Manage skill resources with SMAPI

When you manage Alexa skills by using the ASK CLI or the Alexa Skill Management API (SMAPI), use the corresponding JSON schema for the given skill resources. For details, see the following topics:

Team development best practices

The following sections include best practices for developing Alexa skills by using the ASK CLI with a team.

Account management

To follow the OAuth 2.0 standard, the ASK CLI uses the authorization code grant approach. The ASK CLI is a client-side tool, so it's your responsibility to ensure the security of the refresh token that's used to retrieve the access token. Good security practices require additional caution when a skill is being developed by a team. In this case, 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 Amazon account. The access for other developers, each of whom should also use their own Amazon account, 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 details about managing a single account with multiple users, see Manage Your Amazon Developer Account and Permissions.

Compromised accounts

If you suspect that your account has been compromised, use the following solutions based on your situation:

To revoke all refresh tokens

Log in to Amazon.com.
In the Your Account section, navigate to Manage Login with Amazon.
Remove your application.
Removing your application invalidates the refresh tokens that your team stored in the ASK CLI. The non-expired access token continues to work.
Next time you authenticate through Login with Amazon, follow the prompts from Login with Amazon to grant the scopes and create the ASK CLI application again.

To reset the password for your Amazon account

Follow the instructions in Reset Your Password.
After you reset your password, follow the on-screen instructions to revoke all refresh tokens. This procedure invalidates the refresh tokens stored in the ASK CLI.

Was this page helpful?

Provide feedback

Last updated: Aug 08, 2024