Tutorial: Set up the ASK CLI to Use Alexa Conversations Description Language

With 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 prerequisites.

Establish the necessary accounts and permissions

  1. If you don't already have an Amazon developer account, go to the ASK developer console to open one.
  2. If you don't already have an Amazon Web Services (AWS) account, go to AWS to create an IAM user account.

Update your existing software

  1. Update to the latest version of Node.js (version 16.17 or higher).
  2. For version control, update to the latest version of Git (version 2.37 or higher).
  3. Update your Java development environment (version 8 or higher).
  4. Migrate to the latest version of the AWS Command Line Interface (AWS CLI) (version 2).
  5. Make sure you have the latest version of VS Code (version 1.70 or higher).

    a. Open VS Code, and then click Help.

    b. Click the update-related option, which is either Check for Updates or Restart to Update.

  6. Run the following command to uninstall the public version of the ASK CLI.

    npm uninstall -g ask-cli

Process

Complete the following steps to install and configure the ASK CLI. 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 ACDL syntax highlighter for VS Code

Step 1: Install the ASK CLI

In this step, you use npm to install a beta version of the ASK CLI. The beta version supports Alexa Conversations.

To install the ASK CLI beta version from the command line

  • Open your terminal, and then run the following command.

    npm install -g ask-cli-x

Step 2: Configure the ASK CLI

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

Configure the ASK CLI to recognize your developer account

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

    askx 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 the ASK CLI skill, select the checkbox.
  4. Sign in to the AWS Key Management Service (KMS) as an IAM user.
  5. Choose a symmetric access key (a single 256-bit secret encryption key).

(Optional) Step 3: Install the ACDL syntax highlighter for VS Code

In this step, you install the ASK Toolkit for Visual Studio (VS) Code. The toolkit provides a syntax highlighter and a dedicated VS Code workspace in which to create, test, and deploy Alexa skills. ACDL syntax highlighting is currently available only for VS Code.

To install the ACDL Toolkit for VS Code

  1. Install the ASK Toolkit VS Code extension (version 2.10 or higher), or update it to the latest version.

    a. Open VS Code and click Code > Preferences > Extensions.

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

    c. Click the gear icon, and then click Install another version > 2.10.

    d. Close and then reopen VS Code.

  2. To test the syntax highlighter, create a new ACDL file or open an ACDL project file.

Troubleshooting

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

Issue: ENOENT error

Symptoms

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

   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

  1. To make sure you have the latest npm package (version 8.5 or higher), run the following command.

    $ sudo npm i -g npm
    
  2. To remove package-lock from your JSON file, run the following commands.

    $ rm package-lock.json
    $ npm i
    $ sudo npm i -g .
    
  3. To switch to the last working version of npm, run 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 I try to install the ASK CLI, I get an AWS error message, such as a notice that my account couldn't be linked.

Try this

If you receive an AWS error message, log in to your AWS account to configure the following settings.

  1. Make sure your skill is linked to an IAM user, not a root user.
  2. Make sure your access key ID and secret access key match the credentials you entered.
  3. Make sure your access keys aren't expired.
  4. Confirm that your user configuration includes the necessary policies and permissions.

Issue: Other error message

Symptoms

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

Try this

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