See Quick Start Alexa Command Line Interface for information on setting up the Alexa Skills Kit Command Line Interface (ASK CLI). This document describes all of the commands available through ASK CLI.

ASK CLI Commands

ASK CLI has two different kinds of commands for manipulating skills associated with your developer account.

High-level commands that can perform several actions with one command. These are the best commands to start with if you are new to skill development, or if you don't need to finely control API calls. Thus, new, deploy, clone, and simulate are high-level commands.

Low-level commands that can be used to control individual parts of your Alexa Skills. These commands are thin wrappers over the Alexa Skill Management API operations, so these give you fine-grained control of ASK CLI actions. These commands are particularly useful when you want to change portions of a skill that you have already added to your account. Thus, api and lambda are low-level commands.

$ ask <command> <subcommand> [options]

ASK CLI commands enable you to complete the following tasks:

Task

Command or Option

Get help for tool or for a specific command.

ask [command] -h | --help

Check the version number.

ask -v | --version

Initialize ASK CLI with your Amazon developer account credentials. Run this command to initialize the tool with your developer account credentials before performing skill operations. Note that this command uses port 9090 and if this port is already in use, you will get an error.

If this is your first time initializing ASK CLI, grant permission to ASK CLI.

When you have successfully signed in to your developer account and granted permission to ASK CLI, close the browser and return to the command prompt.

If you have one vendor ID associated with your account, it will now be configured to use ASK CLI.

If you receive a 401 Unauthorized error, you are not authorized to use the Alexa Skill Management API.

If you have more than one vendor ID associated with your developer account, you will be prompted to choose a vendor. This occurs if you manage Alexa skills for more than one organization. To check your vendor ID for a particular organization, sign in to your developer account developer.amazon.com. Choose the organization you want to manage skills for from the dropdown menu at the upper right. Go to
(https://developer.amazon.com/mycid.html](https://developer.amazon.com/mycid.html) to view the vendor ID for that organization.

If you receive the following error: Token refresh error, your authorization token has expired, and ASK CLI is unable to refresh the token. You should check your Internet connection and try again.

You should get the following output: "Profile Vendor ID updated", which means you have successfully initialized ASK CLI. You can view the vendor associated with ASK CLI at the following locations:

Linux/Mac: ~/.ask/cli_config

Windows: %USERPROFILE%/.ask/cli_config

Options:

--no-browser

Optional. This provides an alternative method to initialize ASK CLI without opening the browser in the same developing environment. Instead, you can copy the url displayed in the console and open the link with a web browser anywhere. This will direct you to the login page of Amazon. Sign in and copy the Authcode back to the terminal, then you have initialized ASK CLI successfully.

This feature is aimed to provide a convenient initialization workflow for the developers who need to use ask-cli in a console-only environment.

--profile, -p

Optional. The profile to be updated or created. If not included, the default profile is used.

--list-profiles, -l

Optional. Lists all profiles in the developer's environment.

--debug

Optional. Appends a debug message to the standard error.

Note: You can change the organization whose skills you are managing by running the $ ask init command again and selecting a different vendor ID.

new command

Creates a new skill project in the current directory. Use the new command to create the directories and files necessary to deploy a skill with minimal modifications.

The name of the parent directory for the skill matches the specified skill name, and the parent directory contains files and directories necessary for using ASK CLI to manage the skill. The following example shows directories and files created for a custom skill in the en-US locale.

Optional. The template from which to generate the skill package. When template-name is omitted, ASK CLI provides a prompt for choosing a template from a list. Optionally, specify --url <url> to provide your own list of templates. Verify that the URL for the list is publicly accessible and that the repositories for the templates are public. The default list https://s3.amazonaws.com/ask-cli/templates.json uses repositories at Alexa GitHub. Be aware when using --template that the skill name defaults to the template name if you omit --skill-name.

--skill-name, -n

Optional. The skill name to assign to the skill, which can contain letters (a-z), numbers (0-9), underscores (_) and dashes (-). When you specify --template and omit --skill-name, the skill name defaults to the template name. When not using --template, if --skill-name is omitted, ASK CLI provides a prompt for specifying the skill name.

--profile, -p

Optional. The profile under which the skill is created. If not included, the default profile is used.

--lambda-name

Optional, and only valid when --template is omitted. The name of the AWS Lambda function for the skill.

For a smart home skill, your skill.json file and code files will be deployed.

For a flash briefing skill, only the skill.json file will be deployed.

If the skill has never been deployed, ASK CLI will create a new skill and a new AWS Lambda function named ask-<skillType>-<skillName>-<profile> (with the appropriate type, name, and profile for <skillType>, <skillName>, profile).
The AWS Lambda function is created with an IAM role named "ask-lambda--", attached to the [basic execution policy](http://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html#lambda-intro-execution-role). Make sure your AWS user account has permissions to enable Role creation or this step will fail.

The newly created skill ID and AWS Lambda ARN are written to the skill configuration file at $HOME/.ask/config.

If the skill already exists, ASK CLI will update the existing skill, including metadata, sample utterances, and so on, as well as AWS Lambda function resources if applicable. If this skill package has been created by previously downloading an existing skill using ask clone, and you perform ask deploy on the package for the first time, then ASK CLI will prompt you to ensure you want to overwrite the existing skill in your account.

In the skill.json file, the endpoint object change as follows when deploying a skill with an AWS ARN, if the skill has this format for uri:

Optional. This provides developers an asynchronous choice and experience to deploy. By setting this flag, the deploy command will skip waiting for the model to build.

--target, -t

Optional. `target` indicates whether you want to deploy the AWS lambda code for a skill, the skill project, or both. Accepted values for `target` are: `all`, `lambda`, `skill`, and `model`. The default target is `all`, if not specified.

--profile, -p

Optional. The profile under which the skill is created. If not included, the default profile is used.

--debug

Optional. Appends a debug message to the standard error.

The changes that occur for each endpoint:uri format are shown below.

Has sourceDir

Does not have sourceDir

uri:arn

Update the lambda function to use the codebase from sourceDir

Do nothing

uri: function-name (can find ARN by calling AWS)

update lambda user codebase from sourceDir

Do nothing

uri: function-name (newly created, cannot find on AWS)

Create lambda, and use the function name and the codebase

Error

uri: https

Do nothing

Do nothing

No uri

Create lambda, user, skill-name, and the code base, and then put the ARN back to the config file

Error if there is an apis object.

clone command

Creates a new local skill project by cloning an existing skill from its development stage. You cannot clone a skill from its live stage.

Note: If there is an existing skill project directory with the same name as the skill being cloned, the directory will be overwritten.

Optional. The skill ID for the target skill. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--profile, -p

Optional. The profile under which the skill is cloned. If not included, the default profile is used.

--debug

Optional. Appends a debug message to the standard error.

If ask clone is run without options, then a list of skills (sorted by LastModified) will be displayed, and the user can select the skill from the list to clone.

Otherwise, with a specified skill-id, the command clones the skill to the current directory. It will also download the support domain's model and lambda function, if available. If the skill code has been hosted as a web service, rather than with an AWS lambda function, then this is not downloaded.

After the download of the skill definition, it places the lambda function ARN into the .ask/config file. and replaces the endpoint:uri property in the skill.json file with 'sourceDir', which is the source directory for the codebase for the lambda function.
If the skill has been hosted as a web service, instead of lambda. then no replacement occurs.

simulate command

Calls ask api simulate-skill and continues polling for the simulation status until that is finalized. The parameters are the same as for ask api simulate-skill.

Do not use if <-t, --text> is specified. Otherwise, required. File path to the simulation utterance text content. Can be an absolute or relative path.

--text, -t

Do not use if <-f, --file> is specified. Otherwise, required. Utterance text input with which to simulate the skill.

--locale, -l

Optional if ASK_DEFAULT_DEVICE_LOCALE environment variable is set, otherwise, required. Locale for the skill to be simulated. Valid values are en-US, en-GB or de-DE. If not specified, you will be prompted to enter the locale.

--skill-id, -s

Required. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--profile, -p

Optional. To use a profile other than the default, include the profile name.

--debug

Optional. Appends a debug message to the standard error.

api command

The api command provides a number of subcommands that enable you to create and modify skills associated with your developer account. There are subcommands for creating and updating the skill, interaction model, and account linking information as well as starting the skill certification process.

For detailed description of the interaction model description, see interaction model.

get-skill-status subcommand

Required. The skill ID you are checking status for. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--profile, -p

Optional. The profile under which the skill status is retrieved. If not included, the default profile is used.

--debug

Optional. Appends a debug message to the standard error.

head-model subcommand

Enables you to get the ETag for the model of the skill with the specified skillId and locale. An Etag is a unique identifier for a version of a resource and enables you to validate the model hasn't changed before performing operations on it.

The complete list of skills for the specified vendor are returned. If any of these skills are invalid or corrupted, then that skill will have the skillId, stage, lastUpdated, and publicationStatus values returned, but not the nameByLocale value.

Options:

--profile, -p

Optional. To use a profile other than the default, include the profile name.

--debug

Optional. Appends a debug message to the standard error.

add-private-distribution-account subcommand

Adds an account to the private distribution list for a specified skill.

Required. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--file, -f

Do not use if <-j, --json> is specified. Otherwise, required. File path to the skill invocation request. The request format is defined in here. Can be an absolute or relative path.

--json, -j

Do not use if <-f, --file> is specified. Otherwise, required. JSON string.

--endpoint-region, -e

Required. Indicates the endpoint region used by the skill. Can be "NA", "EU", "FE", or "default". The "default" region is determined from the global default endpoint specified by apis.custom.endpoint in the skill manifest. </dd>

--profile, -p

Optional. To use a profile other than the default, include the profile name.

<dt>--debug</dt>
<dd>Optional. Appends a debug message to the standard error.</dd>

</dl>

simulate-skill subcommand

Simulates the specified skill. Before this command can be used, the skill must first be enabled through the Alexa app.

Do not use if <-t, --text> is specified. Otherwise, required. File path to the simulation utterance text content. Can be an absolute or relative path.

--text, -t

Do not use if <-f, --file> is specified. Otherwise, required. Utterance text input with which to simulate the skill.

--locale, -l

Optional if ASK_DEFAULT_DEVICE_LOCALE environment variable is set, otherwise, required. Locale for the skill to be simulated. Valid values are en-US, en-GB or de-DE. If not specified, you will be prompted to enter the locale.

--skill-id, -s

Required. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--profile, -p

Optional. To use a profile other than the default, include the profile name.

--debug

Optional. Appends a debug message to the standard error.

get-simulation subcommand

Get the simulation result for a specific simulation ID. Each time the simulate-skill command is run, a simulation ID results.