Set up the ASK CLI to Use Alexa Conversations Description Language

With version 2.29 of the Alexa Skills Kit Command Line Interface (ASK CLI), you can use Alexa Conversations Description Language (ACDL) to build and deploy turn-by-turn Alexa Conversations skills. Alexa Conversations uses deep learning to create Alexa skills in which dialog flows naturally between Alexa and the user.

Prerequisites

Before you install and configure the ASK CLI, you must meet the following requirements.

Accounts and permissions

• Amazon developer account – If you don't already have an Amazon developer account, sign up at developer.amazon.com.
• AWS account – If you don't already have an Amazon Web Services (AWS) account, sign up at aws.amazon.com/account.

Software updates

• Update to the latest release of Node.js (version 14 or later).
• For version control, use the latest release of Git (version 2.40 or later).
• Update your Java development environment to the latest stable release.
• Migrate to version 2 of the AWS Command Line Interface (AWS CLI).

• Use the latest version of VS Code.

  To install the latest version of VS Code

  1. Open VS Code.
  2. On the Code tab, click Help.
  3. Click Check for Updates.

Steps to install and configure the ASK CLI

To install and configure the ASK CLI, complete the following steps. Then use ACDL to create Alexa Conversations skills on the command line.

1. Install the ASK CLI
2. Configure the ASK CLI
3. (Optional) Install the ASK Toolkit for VS Code
4. Compile your ACDL skill artifacts
5. Deploy your skill

Step 1: Install the ASK CLI

In this step, you use npm to install the version of the ASK CLI that supports Alexa Conversations. Version 2.29 or later is recommended. For details, see Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI).

To install the latest ASK CLI version

1. To install the latest public version of the ASK CLI, at the command prompt, enter the following command.

   npm install -g ask-cli

Step 2: Configure the ASK CLI

In this step, you configure the ASK CLI to link to your Amazon developer account. This configuration verifies your identity so you can access ASK CLI resources.

To configure the ASK CLI to recognize your developer account

1. To link the ASK CLI to your developer account, enter the following command.

   ask configure

2. Choose the default profile, or enter a name to create a new profile.
3. To grant permission to link your AWS profile to your ASK CLI skill, select the checkbox.
4. Go to the AWS Key Management Service, and sign in as an IAM user.
5. Choose a symmetric access key (a single 256-bit secret encryption key), and then click Save and Continue.

Step 3: (Optional) Install the ASK Toolkit for VS Code

In this step, you install the ASK Toolkit for Visual Studio (VS) Code version 2.14 or later, or you update your existing extension to the latest version. The toolkit provides a syntax highlighter and dedicated VS Code workspace in which to create and test Alexa skills. The ACDL syntax highlighter is currently available only for VS Code.

To install the ASK Toolkit for VS Code

1. Open VS Code, and then click Code > Preferences > Extensions.

2. Search for the Alexa Skills Kit (ASK) Toolkit extension.

3. Click the gear icon, and then click Install.

4. To enable the extension, close and then reopen VS Code.

5. In a new ACDL file or an existing ACDL project file, test the syntax highlighter.

Step 4: Compile your ACDL skill artifacts

ACDL skill artifacts must be compiled before they can be deployed. In this step, you use npm to install the acc command from the @alexa/acdl npm package. Then use the acc command to compile the ACDL artifacts locally to prepare them for deployment.

1. In this step, you use npm to install the @alexa/acdl package. You can install it globally or, if the ACDL skill has a package.json file at the root, you can install it locally.

   • Global installation: npm install -g @alexa/acdl
     
   • Local installation: npm install @alexa/acdl

2. With the @alexa/acdl npm package installed, use the following acc command to compile the skill artifacts.

   npx acc

Step 5: Deploy your skill

In this step, you deploy the compiled ACDL skill artifacts, as well as the endpoint skill handler, using the ASK CLI.

1. To deploy the compiled ACDL skill artifacts and update the skill handler endpoint, enter the following ASK CLI command.

   ask deploy

Troubleshooting ASK CLI installation

If you have trouble with ASK CLI installation, try the following suggestions.

Issue: ENOENT error

Symptoms

When you try to install the ASK CLI, you get an error message similar to the following example.

   npm ERR! code ENOENT
   npm ERR! syscall rename
   npm ERR! path /Users/username/.nvm/versions/node/v17.4.0/lib/node_modules/.staging/ask-cli-e209bd51/node_modules/@babel/generator/node_modules/source-map
   npm ERR! dest /Users/username/.nvm/versions/node/v17.4.0/lib/node_modules/.staging/source-map-4818842b
   npm ERR! errno -2
   npm ERR! enoent ENOENT: no such file or directory, rename '/Users/username/.nvm/versions/node/v17.4.0/lib/node_modules/.staging/ask-cli-e209bd51/node_modules/@babel/generator/node_modules/source-map' -> '/Users/username/.nvm/versions/node/v17.4.0/lib/node_modules/.staging/source-map-4818842b'
   npm ERR! enoent This is related to npm not being able to find a file.
   npm ERR! enoent

   npm ERR! A complete log of this run can be found in:
   npm ERR! /Users/username/.npm/_logs/2022-02-09T04_38_12_058Z-debug.log

Try this

Make sure you have the latest npm package, which is version 8.5 or later.

To make sure your npm package is up to date

1. At the command prompt, enter the following command.

   sudo npm i -g npm
   

2. To remove package-lock from your JSON file, enter the following commands.

   rm package-lock.json
   npm i
   sudo npm i -g .
   

3. To switch to the last functional version of npm, enter the following commands.

   sudo npm i -g npm@8.5.1
   npm -v 8.5.1
   rm package-lock.json
   npm i
   sudo npm i -g .
   

Issue: AWS error message

Symptoms

When you try to install the ASK CLI, you get an AWS error message, such as a notice that your account couldn't be linked.

Try this

If you receive an AWS error message, sign in to your AWS account, and check the configuration.

To check your AWS configuration

• Sign in to your AWS account and verify the following items:
  • Your skill is linked to an identity and access management (IAM) user, not a root user.
  • Your access key ID and secret access key match the credentials you entered.
  • Your access keys are valid (not expired).
  • Your user settings and access policy grant the necessary permissions.

Issue: Other error message

Symptoms

When you try to install the ASK CLI, you receive an error message not listed in this document.

Try this

Make sure you didn't miss anything in the installation, review the general instructions for installing the ASK CLI.

Related topics

• About Alexa Conversations Description Language
• Tutorial: Create an Alexa Conversations Skill with ACDL
• Alexa Skills Kit Command Line Interface (ASK CLI) Overview
• Develop Skills with the Alexa Conversations Description Language

Last updated: Nov 27, 2023