Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

Alexa Skills Kit Command Line Interface Overview

The Alexa Skills Kit Command Line Interface (ASK CLI) is a tool that you can use to manage your Alexa skills and related resources, such as interaction models and account linking details, from the command line. You can use it interactively, in scripts, or integrate it with a build system or continuous integration or continuous deployment product that supports command line execution steps. ASK CLI performs skill management actions by calling the Alexa Skill Management API. You can use ASK CLI to create, read, update, and test Alexa skills and connected AWS Lambda functions, and to submit skills for certification or withdraw them.

Get started with ASK CLI

You can install ASK CLI using npm, the JavaScript package manager. For more information, see ASK CLI Quick Start.

ASK CLI enables you to do all of the following from the command line, among other tasks:

Create a new skill project

Use the ask new command to create a new skill project by copying from a template. You can use one of the Amazon-provided templates, or specify your own.

For a syntax reference, see ask new in the ASK CLI command reference.

Use an Amazon-provided template

When you run ask new with no parameters, ASK CLI prompts you to choose a runtime for your new skill, then provides a list of Amazon-provided skill templates. These templates contain all the files and folders necessary for a basic skill. The ask new command copies these files and folders to your computer and puts them in a skill project folder. You can explore the skill project folder to understand how the skill works, and can even deploy the skill (using the ask deploy command) to the development stage for your account. Use these templates as a starting point for creating your own skills.

The Amazon-provided templates also contain hooks, which are scripts triggered by ASK CLI. These scripts run locally, and help to set up the runtime environment for your skill. For more information, see Hooks.

Structure of a skill project folder

When you create a new skill project from one of the Amazon-provided templates, the skill project contains the following files and folders:

skill project folder
|-- .ask
    |-- config
|-- hooks
    |-- post_new_hook
    |-- pre_deploy_hook
|-- lambda
    |-- source code files for the Lambda function
|-- models
    |-- JSON files, one per locale, containing interaction models (for example, en-US.json)
|-- skill.json

The following list explains each part of the skill project:

  • .ask – A hidden folder that contains the ASK CLI's config file.
  • hooks – A folder that contains the hook scripts. Amazon provides two hooks, post_new_hook and pre_deploy_hook.
  • lambda – A folder that contains the source code for the skill's AWS Lambda function. The files contained here depend on the runtime for the skill.
  • models – A folder that contains one more interaction models for the skill. Each interaction model is defined in a JSON file named according to the locale. For example, en-US.json and de-DE.json.
  • skill.json – A file that contains the skill manifest.

To create a new skill using an Amazon-provided template

  1. Use the ask new command with no parameters. When prompted, choose a runtime. Use the arrow keys to navigate the list, then use the enter key to select the highlighted option.
    C:\> ask new
    ? Please select the runtime (Use arrow keys)
    > Node.js V8
      Python3
    
  2. Choose one of the Amazon-provided templates. Use the arrow keys to navigate the list, then use the enter key to select the highlighted option.
    C:\> ask new
    ? Please select the runtime Node.js V8
    ? List of templates you can choose (Use arrow keys)
    > Hello World
      Buttons ColorChanger
      City Guide
      Decision Tree
      Fact
      Feed
      Foodie
    (Move up and down to reveal more choices)
    
  3. Type a skill name, or use the enter key to accept the default name. ASK CLI uses this name to create the skill project folder on your computer.
    C:\> ask new
    ? Please select the runtime Node.js V8
    ? List of templates you can choose Hello World
    ? Please type in your new skill name, alphanumeric only: skill-sample-nodejs-hello-world
    Skill skill-sample-nodejs-hello-world has been created based on the chosen template
    

ASK CLI creates a skill project folder and adds all the files and folders from the skill template that you selected. Then ASK CLI runs the post new hook script in the hooks folder. For more information, see Hooks.

Use your own template

You can use your own skill template instead of choosing from one of the Amazon-provided templates. To use your own template, you provide the URL for one of the following:

To use your own skill template, you must have Git installed. For more information, see Installing Git in the Git documentation.

Use a template from a Git repository

To use a skill template from a Git repository, provide the Git URL with the --url parameter, as in the following example.

C:\> ask new --url https://example.com/example/example-skill.git
? Please type in your new skill name, alphanumeric only: example-skill
[Warn]: Downloading skill template from unofficial resource. Please make sure you understand what each script is doing to best protect yourself from malicious usage
? Would you still like to continue execution ? Yes
Skill example-skill has been created based on the chosen template

In this example, ASK CLI prompts for a skill name. You can provide a skill name with the --skill-name or -n parameter.

Use a list of templates

To use a template from a list of templates, provide the URL for a JSON file that contains a list of templates. The JSON file must contain a list of template names, each with a corresponding Git URL. For examples of how to format the JSON file, see the JSON files for the Amazon-provided skill templates:

Provide the JSON URL with the --url parameter, as in the following example.

C:\> ask new --url https://example.com/example/templates/example-templates.json
? List of templates you can choose Example Skill
? Please type in your new skill name, alphanumeric only: example-skill
Skill example-skill has been created based on the chosen template

When the list contains more than one template, ASK CLI prompts you to choose a template, then to type a skill name. You can also provide a template name with the --template parameter, and a skill name with the --skill-name or -n parameter.

Deploy a skill project to the development stage

Use the ask deploy command to deploy a new or updated skill project. A skill project includes:

  • A skill manifest (skill.json file)
  • One or more skill models
  • Source code and configuration for the skill's AWS Lambda function
  • (Optional) One or more in-skill products

For a syntax reference, see ask deploy in the ASK CLI command reference.

Deploy a new skill

When the local skill project has never been deployed, ASK CLI creates a new skill in the development stage for your account, then deploys the skill project. If applicable, ASK CLI creates one or more new AWS Lambda functions in your AWS account and uploads the Lambda function code. Specifically, ASK CLI does the following:

  1. Looks in your skill project's config file (in the .ask folder, which is in the skill project folder) for an existing skill ID. If the config file does not contain a skill ID, ASK CLI creates a new skill using the skill manifest in the skill project's skill.json file, then adds the skill ID to the skill project's config file.
  2. Looks in your skill project's manifest (skill.json file) for the skill's published locales. These are listed in the manifest.publishingInformation.locales object. For each locale, ASK CLI looks in the skill project's models folder for a corresponding model file (for example, en-US.json), then uploads the model to your skill. ASK CLI waits for the uploaded models to build, then adds each model's eTag to the skill project's config file.
  3. Looks in your skill project's manifest (skill.json file) for AWS Lambda endpoints. These are listed in the manifest.apis.<skill type>.endpoint or manifest.apis.<skill type>.regions.<region code>.endpoint objects (for example, manifest.apis.custom.endpoint or manifest.apis.smartHome.regions.NA.endpoint). Each endpoint object contains a sourceDir value, and optionally a uri value. ASK CLI upload the contents of the sourceDir folder to the corresponding AWS Lambda function and names the Lambda function the same as the uri value. For more details about how ASK CLI performs uploads to Lambda, see AWS Lambda deployment details.
  4. Looks in your skill project folder for in-skill products, and if it finds any, uploads them to your skill. For more information about in-skill products, see the In-Skill Purchasing Overview.

Deploy an updated skill

When the local skill project has been previously deployed, determined by the existence of a skill ID in the skill project's config file (in the .ask folder, which is in the skill project folder), ASK CLI updates the existing skill. First, ASK CLI compares the local skill project with the skill in the development stage for your account as described below, to determine the differences.

To compare the differences between your local skill project and the deployed skill, ASK CLI compares the eTag of each skill resource. When they differ, ASK CLI displays the following warning:

-------------------- Update Skill Project --------------------
[Error]: The local stored [skill] eTag does not match the one on the server side.
   Use "ask diff" to inspect the difference between local and remote.
   Use "ask deploy --force" to deploy with the local project version regardless of the eTag.

When there are no differences between the eTag values for the local skill and the deployed skill, or when you specify the --force parameter (ask deploy --force), ASK CLI deploys the skill in generally the same way as described in the deploy a new skill section.

AWS Lambda deployment details

When ASK CLI creates a new Lambda function, it associates the AWSLambdaBasicExecutionRole with the function. For more information, see Manage Permissions: Using an IAM Role (Execution Role) in the AWS Lambda documentation. Make sure the AWS credentials that you configured for use with ASK CLI have permission to create IAM roles and associate permissions.

When ASK CLI creates or deploys Lambda functions, it looks in your skill project's config file (in the .ask folder, which is in the skill project folder) to determine the runtime and handler to use. These values are in the deploy_settings.default.resources.lambda.runtime and deploy_settings.default.resources.lambda.handler fields. Note that deploy_settings.default.resources.lambda is an array, so there might be more than one runtime or handler field. When ASK CLI doesn't find a runtime or handler in the config file, it uses the default values of "Node.js 8.10" for the runtime, and "index.handler" for the handler.

To determine the AWS region where it creates or deploys Lambda functions, ASK CLI looks in your skill project's manifest (skill.json file) for AWS Lambda endpoints. These are listed in the manifest.apis.<skill type>.endpoint object, known as the default endpoint, or in manifest.apis.<skill type>.regions.<region code>.endpoint objects, known as region-specific endpoints. ASK CLI uses the following rules to determine the AWS region to use:

ASK region code AWS region code AWS region name
default or NA us-east-1 US East (N. Virginia)
EU or IN eu-west-1 EU (Ireland)
FE us-west-2 US West (Oregon)

To determine whether to create new Lambda functions or update existing ones, ASK CLI looks at the uri value in each endpoint object in your skill project's manifest (skill.json file). Using the ASK region code (see the preceding table) and uri value together, ASK CLI looks for an existing Lambda function with the same name as the uri value. If it finds one, ASK CLI updates the existing Lambda function. Otherwise it creates a new one. When there is no uri value in the skill project's manifest, ASK CLI uses information in the skill project's config file (in the .ask folder) to create one.

To customize the name of the Lambda function that ASK CLI creates or updates, modify the uri value in each endpoint object in your skill project's manifest (skill.json file). In some cases, ASK CLI might not use the uri value for your Lambda function name. This happens when you used a previous version of ASK CLI and the skill project's config file (in the .ask folder) contains a merge field. In this case, we recommend that you delete the merge field in the skill project's config file.

Hooks

Hooks are scripts that are triggered by ASK CLI. ASK CLI supports two hooks:

  • The post new hook, which automatically runs at the end of the ask new command.
  • The pre deploy hook, which automatically runs at the beginning of the ask deploy command.

The Amazon-provided hooks help to set up the runtime environment for your skill. The following sections explain what the Amazon-provided hooks do, when ASK CLI runs hooks, and when ASK CLI adds hooks to your skill project.

What the Amazon-provided hooks do

The Amazon-provided hooks help to set up the runtime environment for your skill. The details differ depending on your skill's runtime.

For a Node.js skill, the post new and pre deploy hooks have the same effect. Each script does the following:

  1. Looks in your skill project directory, in the skill.json file, for source directories. These are specified in the sourceDir element.
  2. For each source directory, runs npm install to install the dependencies listed in the package.json file in the source directory. The dependencies are installed to the node_modules folder in the source directory.

To view the source of each script, see the following links:

For a Python skill, the post new hook does the following:

  1. Looks in your skill project directory, in the skill.json file, for source directories. These are specified in the sourceDir element.
  2. For each source directory, creates a Python virtual environment using venv or virtualenv.
  3. In the virtual environment, runs pip to install the dependencies listed in the requirements.txt file in the source directory. The dependences are installed in the virtual environment.

To view the source of the post new hooks, see the following links:

The pre deploy hook does the following:

  1. Looks in your skill project directory, in the skill.json file, for source directories. These are specified in the sourceDir element.
  2. For each source directory, creates a folder named lambda_upload.
  3. Copies source code from the source directory to the lambda_upload folder.
  4. Copies dependencies from the virtual environment to the lambda_upload folder.
  5. Updates the relevant sourceDir values in the skill.json file to the lambda_upload folder.

To view the source of the pre deploy scripts, see the following links:

When ASK CLI runs hooks

ASK CLI runs the post new hook at the end of the ask new command, and the pre deploy hook at the beginning of the ask deploy command. These commands look for a hooks folder in your skill project folder, and then run script files named post_new_hook (run by ask new) and pre_deploy_hook (run by ask deploy). If the commands don't find a hooks folder, they create one and then download the Amazon-provided hooks. For more information, see when ASK CLI adds hooks and what the Amazon-provided hooks do.

When ASK CLI adds hooks

ASK CLI looks for a hooks folder in your skill project folder at the following times:

  • The end of the ask new command
  • The end of the ask clone command
  • The beginning of the ask deploy command

When ASK CLI doesn't find a hooks folder, it downloads the Amazon-provided hooks. For more information about these hooks, see what the Amazon-provided hooks do.

Object schemas

When you manage Alexa skills with ASK CLI or SMAPI, you need the JSON format for representing each resource. For more information, see:

Develop a skill with a team of developers

ASK CLI facilitates creating a skill with a team of developers, as described in the following sections.

Team account management best practice

ASK CLI uses the Authorization Code grant approach following the OAuth 2.0 standard. ASK CLI is a client-side tool, so it's your responsibility to ensure the security of the refresh token which can retrieve the access token. Good security practice requires additional caution when a skill is being developed by a team, as 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 should also have an unshared customer account. The access for other developers, each of whom should also use their own customer accounts, 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 more information about managing a single account with multiple users, see Manage Your Amazon Developer Account and Permissions.

Solution to compromised account

If you suspect your account has been compromised, you can follow the solution based on your situation below.

If you need to:

  • Revoke all the refresh tokens: Turn to Your Account > Manage Login with Amazon and remove your application from there. By doing this, all the refresh tokens that your team has already stored in ASK CLI will be invalidated, but the non-expired access token will still work. The next time that you authenticate through Login with Amazon, you will be prompted to grant the scopes again. Then the ASK CLI application will be created again in Login with Amazon.

  • Reset password for your Amazon account: After you reset your password, you must revoke the refresh token by following the instructions in the previous point. This guarantees that all the refresh tokens that have been stored in ASK CLI are revoked.