ASK CLI v1 to v2 Migration Guide

This guide describes changes between Alexa Skills Kit (ASK) Command Line Interface (CLI) v1 and v2 and the steps you might need to take to produce the same behavior in ASK CLI v2.

Upgrade your skill project structure

For skills created with ASK CLI v1.x, you need to update the project structure to deploy with ASK CLI v2. To help you upgrade your projects to the new format, consider using the ask util upgrade-project command for each skill.

To install the ASK CLI v2 and upgrade your skill project structure, follow these steps:

  1. Using ASK CLI v1.x, deploy your skill: 
     $ ask deploy
  2. Install ASK CLI v2: 
     $ npm install -g ask-cli@2
  3. Upgrade your skill project with ASK CLI v2. From the root of your project, run: 
     $ ask util upgrade-project

    The command makes the following changes to the CLI v1 project structure:

    Project component v1.x v2.x
    Project configuration .ask/config ask-resources.json
    Skill package skill.json skill-package/skill.json
      models/xx-YY.json skill-package/interactionModels/xx-YY.json
      isps/ skill-package/isps/
      … …
    Skill code lambda/ lambda/
    Skill hosting infrastructure N/A infrastructure/

    The upgrade-project command removes hooks/ from project templates. Hooks are no longer required for deployment.

    The upgrade-project command doesn't make any changes to existing Amazon Web Services (AWS) resources. ASK CLI v2 uses the existing AWS Lambda Amazon Resource Names (ARNs) for a skill.

    Before the upgrade, the command creates a hidden folder named ./legacy that contains a copy of your v1 skill project. If the upgrade doesn't succeed, use the contents of the ./legacy folder to restore your skill project to its prior state.

  4. Confirm successful upgrade with a CLI v2 deploy after the upgrade: 
     $ ask deploy

If you encounter issues during the upgrade process, create an issue on GitHub.

Replace ask api with ask smapi

ASK CLI v2 replaces the ask api command with the ask smapi command to show that the command interacts with the Skill Management API (SMAPI). For details, see the smapi command reference.

Replace ask init with ask configure

ASK CLI v2 replaces the ask init command with the ask configure command to configure the ASK CLI with your Amazon developer account credentials.

Add ask init for initializing an exiting skill for deployment

ASK CLI v2 now uses ask init for initializing an existing skill project for deployment with the ASK CLI.

Replace ask deploy with git push for Alexa-hosted skills

For Alexa-hosted skills, ASK CLI v2 now requires a git push to the remote repository to deploy. The ask deploy command has no effect for Alexa-hosted skills. For details, see Deploy Alexa-hosted skills with Git." %}

Replace ask created-hosted-skill with ask new

ASK CLI v2 removes the ask create-hosted-skill command for creating an Alexa-hosted skill. To create a new Alexa-hosted skill in CLI v2, run ask new and select Alexa-hosted as the hosting solution.

Remove ask clone

ASK CLI v2 removes the clone command for cloning an AWS-hosted skill to a local machine.

To migrate skill code hosted on AWS Lambda to a local machine, export the skill code from AWS Lambda. After you download the skill code, run ask init within the project directory to download Alexa Skill Package resources and set up the project for deployment using the ASK CLI.

To migrate an Alexa-hosted skill code to a local machine, run ask init --hosted-skill-id HOSTED_SKILL_ID with the skill identifier of the Alexa-hosted skill.

Remove In-Skill Purchasing commands

ASK CLI v2 removes high-level commands add, remove, and status for adding, removing, and reviewing the status of In-Skill Purchasing (ISP) changes to a skill. ISP resources are now managed with the Skill Package resources. You can now add and remove ISP JSON files directly from the skill-package/isps directory of a skill project and deploy the skill.

Remove ask simulate

ASK CLI v2 removes the high-level simulate command. Use the following two commands to simulate a skill and retrieve the simulation result:

  1. simulate-skill
  2. get-skill-simulation

Remove ask validate

ASK CLI v2 removes the high-level validate command. Use the following two commands to validate a skill and retrieve the validation result:

  1. submit-skill-validation
  2. get-skill-validations

Remove ask lambda

ASK CLI v2 removes the lambda command for downloading and uploading code to AWS Lambda. Install and use the AWS CLI to manage AWS Lambda functions directly.

Remove ask diff

ASK CLI v2 removes the diff command for comparing local and remote Alexa skill resources. Make sure to always maintain your authoritative source code in your local repository, and then push to the remote to deploy changes.

Last updated: Apr 05, 2021