ASK CLI v1 to v2 Migration Guide

This guide describes changes between ASK CLI v1 and v2 and the steps you might need to take to produce the same behavior in ASK CLI v2.

New skill project structure required for deployment with CLI v2

For skills created with ASK CLI 1.x, you need to 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 to attempt the necessary changes.

To perform the upgrade:

  1. Using ASK CLI 1.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 command also creates a hidden folder named ./legacy that contains a copy of your v1 skill project prior to the upgrade. 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
    

Notes:

  • The upgrade-project command assumes that you create the project using CLI v1
  • No changes are made to existing AWS resources. ASK CLI v2 uses the existing Lambda ARN(s) for a skill.
  • hooks/ have been removed from project templates and are no longer required for deployment.

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

Replace ask init with ask configure

ASK CLI v2 replaces the ask init command with the ask configure command to show the purpose of the command.

Add ask init for initializing an exiting skill for deployment with ASK CLI

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

Replace ask deploy for Alexa-hosted skills with git push

For Alexa-hosted skills, ASK CLI v2 now requires a git push to the remote Alexa-hosted skills master branch to deploy. ask deploy has no effect for Alexa-hosted skills.

Remove ask created-hosted-skill and use ask new instead

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 the skill code has been downloaded, 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 high-level ISP commands add, remove, and status

ASK CLI v2 removes high-level commands add, remove, and status for adding, removing, and reviewing the status of 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.