ASK CLI Command Reference

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 simplify working with skill projects, often by abstracting details and performing several actions under the hood. 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. init, new, deploy, clone, validate, and simulate are high-level commands.
  • Low-level commands can be used to control individual parts of your Alexa Skill. These commands are thin wrappers over the Alexa Skill Management API operations, so they give you fine-grained control over each API call. These commands are particularly useful when you want to change portions of a skill that you have already added to your account. The api and lambda commands are low-level.

$ 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. ask init
Create a new Alexa skill project on your computer, with the necessary folders and files to deploy it with minimal changes. ask new
Deploy a skill to your developer account including your skill manifest, interaction model, and AWS Lambda functions. ask deploy
Create a skill project by cloning an existing skill to a local skill project. ask clone
List the differences between the local and remote versions of a project. ask diff
Executes validation tests on a skill. ask validate
Simulates an invocation of your skill with text input. The parameters are the same as for ask api simulate-skill. ask simulate
Provides utility tools to manage Alexa skill development ask util [subcommand]
Create and update the AWS Lambda function code, independent of skill management. ask lambda [subcommand]
Manage details of Alexa skills associated with your developer account. Use these commands if you want to create or update portions of an Alexa skill. ask api [subcommand]
Create and manage in-skill products See the In-Skill Product Command Reference

init command

To establish authorization for the CLI to create and modify skills associated with your Amazon developer account, you must run the init command.

init command format:

$ ask init [-p| --profile <profile>] [--no-browser] [-l| --list-profiles] [--aws-setup] [--debug]

  1. In the CLI command window, enter ask init. You will be prompted to create a profile, or to select the default profile. If this is the first time you have run this command on this machine, the default profile is selected. If you have previously created a non-default profile, you can also choose that one.
  2. If you are creating a new non-default profile, you will be prompted to enter the profile name. If you leave the name blank, it will be default.
  3. If you have not previously set up AWS credentials, you will be prompted to do so. You can either set up the AWS credentials directly (Option 1), or you can set AWS environment variables (Option 2), or you can opt to skip AWS setup if you prefer.

Option 1: Set up AWS credentials directly

  • In the CLI command window, select "Yes, Setup the AWS credentials". This choice is equivalent to selecting ask init --aws-setup. You will be prompted to enter your profile name, your access key, and your secret access key. See Set Up Credentials for an Amazon Web Services Account. By default, a browser window will open with a sign-on screen.
  • Sign in with your Amazon developer account credentials.
  • 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. Your AWS credentials file is at %USERPROFILE%/.aws/credentials.

Option 2: Set up AWS environment variables

  • In the CLI command window, select "No. Use the AWS environment variables." By default, a browser window will open with a sign-on screen.
  • Sign in with your Amazon developer account credentials.
  • 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.
  • Log in to the AWS console. Hover over your name at the top right, and select My Security Credentials. Click Create Access Key. In the popup that appears, click Show Access Key. Copy the values you see there, or download the file.
  • Next, you will export these values to create environmental variables.
  • For Linux, to create the AWS environment variables, enter these commands in the CLI window, substituting the values that you have obtained from the AWS console for my_access_key_id_value and my_aws_secret_access_key.
    export AWS_ACCESS_KEY_ID=my_access_key_id_value
    echo AWS_ACCESS_KEY_ID
    export AWS_SECRET_ACCESS_KEY=my_aws_secret_access_key
    echo AWS_SECRET_ACCESS_KEY
    

If you are using Windows, use the set command to similarly create and set the values for the environment variables for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

When you use ASK CLI subsequently, you will be given the option to use the AWS environment variables. Note that ASK CLI only supports these specific AWS environment variables, and not the full set. See AWS Environment Variables.

The following apply no matter which method you use for AWS access.

  • If you have one vendor ID associated with your account, it will now be configured to use ASK CLI.
  • 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 Customer Details to view the vendor ID for that organization.

     $ Choose the vendor ID for the skills you want to manage
     1) Amazon: M123456789
     2) Sample-Vendor: M987654321
    
  • 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 [profile name] initialized successfully.", which means you have successfully initialized ASK CLI. You can view the vendor associated with ASK CLI profiles 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, copy the URL displayed in the console and open the link with a web browser on another device. This will direct you to the login page of Amazon. Sign in and copy the Authcode back to the terminal, and then you have initialized ASK CLI successfully.
This feature is aimed to provide a convenient initialization workflow for the developers who need to use the ASK CLI in a console-only environment.
--profile, -p
Optional. The profile to be updated or created. If the specified profile already exists, the CLI will overwrite the profile with the user's inputs. If not provided, the CLI will start an interactive prompt that lets the user either create a new profile or update an existing one.
--list-profiles, -l
Optional. Lists all profiles in the developer's environment.
--aws-setup

Optional. Use the --aws-setup option to create or edit your credentials file if necessary. You will be prompted to enter your profile name, your access key, and your secret access key. See Set Up Credentials for an Amazon Web Services Account.

--debug
Optional. Appends a debug message to the standard error.

new command

Creates a new skill project under the current directory. Use the new command to create the directories and files that represent new skill in the local file system. All sample skill projects created using the new command can be immediately deployed with the ask deploy command.

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.

-skillName
   -.ask
      -config
   -lambda
      -custom
        -index.js
   -models
      -en-US.json
   -skill.json

The skill is created with the default profile information contained in the $HOME/.ask/cli_config file. The {skillName}/.ask/config file will contain per-profile deployment settings like skill_id.

new command format:

ask new [--template [template-name] [--url <url>]] [-n|--skill-name <name>] [-p| --profile <profile>] [--lambda-name <lambda-name>]

To use the template parameter, you must have git installed on your machine. See Installing Git.

Options:

--template [template-name] [--url <url>]
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. In order to use these templates, you must have git installed on your machine.
--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. If not provided, the Lambda function name will be based on skill name.

deploy command

Deploys a skill project, including any in-skill products, to your developer account, optionally deploying AWS Lambda code. For more information about in-skill products, see the In-Skill Product Command Reference. If you have previously deployed the project, it is recommended that you run the diff command first to view the differences between the local and remote versions.

Use deploy to create a new skill

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-<skill name>-<profile>, attached to the basic execution policy. 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.

Use deploy to update skill project

If the skill already exists, ASK CLI compares the local and remote versions. If the --force option is not used, and the two versions differ, ASK CLI informs the user, as follows, and gives the following recommendations.

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

If the ask deploy --target <target> command is used, ASK CLI will update the specified target with the local version. If no target is specified, then the existing skill, including the skill manifest, interaction model, lambda, and in-skill products will all be updated.

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:

"apis": {
  "custom": {
    "endpoint": {
      "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
    },
    "regions": {
      "NA": {
        "endpoint": {
          "uri": "https://customapi.sampleskill.example.com",
          "sslCertificateType": "Trusted"
        }
      }
    }
  }
}

Deploying it will change it to this format:

"apis": {
    "custom": {
      "endpoint": {
           "sourceDir": "./lambda/custom"
      },
      "regions": {
        "NA" : {
          "endpoint": {
            "uri": "https://customapi.sampleskill.example.com",
            "sslCertificateType": "Trusted"
          }
        }
      }
}

deploy command format

deploy command format:

ask deploy [--no-wait] [-t| --target <target>] [--force] [-p| --profile <profile>] [--debug]

Options:

--no-wait
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 and will not automatically enable the deployed skill. If you use –no-wait, ensure that you use the –force option the next time you use the deploy command, since without the use of –force, the deploy command will compare eTags and this eTag comparison may be incorrect because the previous deploy command was completed without waiting for the model to be built.
--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`, `model`, and `isp`. The default target is `all`, if not specified.
--force
Optional. If used, the remote version of the target is updated with local changes without confirmation.
--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 sourceDirDoes not have sourceDir
uri:arnUpdate the lambda function to use the codebase from sourceDirDo nothing
uri: function-name (can find ARN by calling AWS)update lambda user codebase from sourceDirDo nothing
uri: function-name (newly created, cannot find on AWS)Create lambda, and use the function name and the codebaseError
uri: httpsDo nothingDo nothing
No uriCreate lambda, user, skill-name, and the code base, and then put the ARN back to the config fileError 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. When you clone a skill that includes in-skill purchases, the in-skill purchases will be cloned as well.

clone command format:

$ ask clone [-s|--skill-id <skillId>] [-p| --profile <profile>] [--debug]

Options:

--skill-id, -s
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 interaction model(s) and lambda function(s), if available. If the skill code is hosted at an HTTPS endpoint, rather than as an AWS Lambda function, then this is not downloaded.

After the download of the skill definition, ASK CLI will put the AWS Lambda function ARN into the .ask/config file and replace the endpoint:uri property in the skill.json file with sourceDir, which is the source directory for the codebase for the lambda function. This is to ensure the portability of the skill project and to enable deployment of the same skill to multiple profiles, if needed. If the skill has been hosted as a web service, instead of AWS Lambda, then no replacement occurs.

diff command

List the differences between the local and remote versions of the specified target. If no target is specified, ASK CLI will show the diff for all resources. ASK CLI will first compare the local and remote eTag, and then tell you if the local version is based on the latest version, and then display the diff results. It is recommended that you run the diff command before using deploy, in order to list differences between the local and remote components of a project.

diff command format:

$ ask diff [-t|--target <target>] [-p| --profile <profile>] [--debug]

Options:

--target, -t
Optional. `target` specifies the project component for which the differences will be listed. Accepted values for `target` are: `all`, `lambda`, `skill`, `model`, and `isp`. The default target is `all`, if not specified.
--profile, -p
Optional. The profile under which the versions of the skill are compared. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

When the differences are listed, you as the developer can manually edit the local version to match what you want. When you have edited the local version as desired, you can then use deploy to update the remote version.

validate command

Executes tests that can be used to validate a skill before submission for certification or at any time during development as regression testing. Refer to Skill Validation API–Supported Validations for supported tests.

This is an asynchronous operation which polls the validation result until it is available. If you prefer to run the validation and obtain the validation results in two separate steps, see validate-skill and get-validation.

validate command format:

$ ask validate [-s|--skill-id <skillId>] [-l|--locales <locales>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Optional. The skill ID for the skill you want to validate. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123 If the skill-id is not specified, then this command must be run under the skill project root directory where the skill to be tested has already been created or cloned. If the skill-id is specified, then the command can be run from anywhere.
--locales, -l
Optional. List of locales. Supported values include: en-US, en-GB, en-CA, en-AU, en-IN. This option is not required if an environment variable named ASK_DEFAULT_DEVICE_LOCALE is set. If this option is not specified and the environment variable ASK_DEFAULT_DEVICE_LOCALE is not set, an error message to specify the environmental variable or the device locale.
--stage, -g
Optional. Indicates stage of the skill. Use development or live as values. Defaults to development.
--profile, -p
Optional. The profile under which the account linking configuration is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

simulate command

Simulates an invocation of your skill with text input. Under the hood, the command calls ask api simulate-skill and continues polling for the simulation status until it is finalized. The parameters are the same as for ask api simulate-skill.

simulate command format:

$ ask simulate [-f| --file <filepath>] [-t| --text <text>] [-l| --locale <locale>] [-s|--skill-id <skillId>] [-p| --profile <profile>] [--debug]

--file, -f
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, en-CA, en-AU, en-IN, de-DE, or ja-JP. If not specified, you will be prompted to enter the locale.
--skill-id, -s
Optional. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123. If not provided, the CLI will find the skill ID from .ask/config file for the current profile.
--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 map 1:1 to the underlying API operations in Alexa Skill Management API (SMAPI). The commands allow detailed control of API inputs and expose raw outputs. There are subcommands for creating and updating the skill, interaction model, and account linking information as well as starting the skill certification process.

api command format:

$ ask api <subcommand>

Subcommands

Task Subcommand
Basic skill management  
Create a new skill create-skill
Get a skill manifest get-skill
Delete a skill delete-skill
Update the skill configuration details update-skill
Get status of a skill after create/update call get-skill-status
Work with skill model  
Get an interaction model for a skill get-model
Update a model, or create a new interaction model for a skill. A build of the model is triggered. update-model
Get the ETag associated with an interaction model head-model
Manage account linking  
Add or update account linking configuration information for a skill create-account-linking
Get account linking configuration information for a skill get-account-linking
Delete account linking configuration information for a skill delete-account-linking
Manage validation and certification  
Execute validation tests on a skill validate-skill
Get the results of the validation get-validation
Submit a skill for certification submit
Withdraw a skill from the certification process withdraw
Manage vendors  
Get the vendor IDs associated with your developer account list-vendors
List skills for a vendor list-skills
Manage private skills  
Add a private distribution account add-private-distribution-account
Delete a private distribution account delete-private-distribution-account
List private distribution accounts list-private-distribution-accounts
Manage skill enablement and disablement  
Enable a skill enable-skill
Disable a skill disable-skill
Get skill enablement get-skill-enablement
Manage skill invocation and simulation  
Invoke a skill invoke-skill
Simulate a skill simulate-skill
Get simulation result get-simulation
Get intent requests history intent-requests-history

create-skill subcommand

Creates a skill associated with your developer account from its skill.json file. Returns the skill ID and the skill status.

create-skill command format:

$ ask api create-skill [-f|--file <fileName>] [-p|--profile <profile>] [--debug]

Options:

--file, -f
Required. File path to the skill information file in .json format. Can be an absolute or relative path.
--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 output.

get-skill subcommand

Outputs the schema for the skill with the specified skill ID to the terminal. You can optionally redirect this output to a file using the > operator as seen below.

$ ask api get-skill -s {skill_id} –-stage development > skill.json

get-skill command format:

$ ask api get-skill [-s|--skill-id <skillId>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. Skill ID for the skill to get. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--stage, -g
Optional. Indicates stage of the skill. Use development or live as values. Defaults to development
--profile, -p
Optional. The profile under which the skill schema is output. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard output.

delete-skill subcommand

Deletes a skill. Once deleted, the skill cannot be retrieved.

delete-skill command format:

$ ask api delete-skill [-s|--skill-id <skillId>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. Skill ID for the skill to delete. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--profile, -p
Optional. The profile under which the skill is deleted. If not included, the default profile is used. This profile must have the right to delete the skill.
--debug
Optional. Appends a debug message to the standard output.

update-skill subcommand

Updates the specified skill with the skill manifest provided with the --file option.

update-skill command format:

$ ask api update-skill [-s|--skill-id <skillId>] [-f|--file <fileName>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. The skill ID for the skill to update. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--file, -f
Required. File path to the skill information file in .json format. Can be an absolute or relative path.
--stage, -g
Optional. Indicates stage of the skill. Only development is supported for this command.
--profile, -p
Optional. The profile under which the skill schema is created or updated. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

get-model subcommand

Retrieves the model schema for the skill with the specified skillId and locale. You can optionally redirect this output to a file using the > operator as seen below.

$ ask api get-model -s {skill_id} –-stage development -l {locale} > model.json

get-model command format:

$ ask api get-model [-s|--skill-id <skillId>] [-l|--locale <locale>] [-p|--profile <profile>] [--debug] [-g|--stage <stage>]

Options:

--skill-id, -s
Required. Skill Id for the target model. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--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, en-CA, en-AU, en-IN, de-DE, or ja-JP. If not specified, you will be prompted to enter the locale.
--stage, -g
Optional. Indicates stage of the skill. Use development or live as values. Defaults to development.
--profile, -p
Optional. The profile under which the model schema is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

update-model subcommand

Enables you to set the specified interaction model schema for the specified skill and locale.

update-model command format:

$ ask api update-model [-s|--skill-id <skillId>] [-f | --file <fileName>] [-l|--locale <locale>] [-p|--profile <profile>] [-g|--stage <stage>] [--debug]

Options:

--skill-id, -s
Required. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--file, -f
Required. File path to the models/{locale}.json file. Can be an absolute or relative path.
--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, en-CA, en-AU, en-IN, de-DE, or ja-JP. If not specified, you will be prompted to enter the locale.
--stage, -g
Optional. Indicates stage of the skill. Defaults to development, which is the only supported value for this command.
--profile, -p
Optional. The profile under which the skill is updated. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

get-skill-status subcommand

Retrieves status of the skill and its interaction models.

get-skill-status command format:

$ ask api get-skill-status [-s|--skill-id <skillId>] [-p|--profile <profile>] [--debug]

--skill-id, -s
Required. The skill ID you are checking status for. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--stage, -g
Required. Indicates stage of the skill. Use development or live as values.
--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.

head-model command format:

$ ask api head-model [-s|--skill-id <skillId>] [-l|--locale <locale>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. Skill ID for the target model. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--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, en-CA, en-AU, en-IN, de-DE, or ja-JP. If not specified, you will be prompted to enter the locale.
--stage, -g
Optional. Indicates stage of the skill. Use development or live as values. Defaults to development.
--profile, -p
Optional. The profile under which the ETag is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

create-account-linking subcommand

Adds or updates account linking configuration details for the specified skill ID.

When you call create-account-linking you will be prompted to enter the following values. For more details on these values, see Configure Authorization Code Grant and accountLinkingRequestObject.

  • Authorization URL
  • Client ID
  • Scopes (comma-separated list)
  • Domains (comma-separated list)
  • Authorization Grant Type - Use arrow keys to choose either IMPLICIT or AUTH_CODE
  • If you choose AUTH_CODE, fill in additional information.
    • Access Token URL
    • Client Secret
    • Client Authentication Scheme: HTTP_BASIC or REQUEST_BODY_CREDENTIALS
    • Default Token Expiration Time In Seconds (optional)

The account linking information will not be stored on your computer due to its sensitive nature.

create-account-linking command format:

$ ask api create-account-linking [-s|--skill-id <skillId>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. The skill ID for the skill to add account linking information for. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--stage, -g
Optional. Indicates stage of the skill. Defaults to development, which is the only supported value for this command.
--profile, -p
Optional. The profile under which the account linking is created. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

get-account-linking subcommand

Gets the account linking configuration details and outputs them to the console. You should not store this information on your computer for security reasons.

get-account-linking command format:

$ ask api get-account-linking [-s|--skill-id <skillId>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. The skill ID for the skill to get the account linking information for. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123
--stage, -g
Optional. Indicates stage of the skill. Use development or live as values. Defaults to development.
--profile, -p
Optional. The profile under which the account linking configuration is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

delete-account-linking subcommand

Deletes the account linking configuration for the specified skill and stage.

delete-account-linking command format:

$ ask api delete-account-linking [-s|--skill-id <skillId>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. The skill ID for the skill to get the account linking information for. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123
--stage, -g
Optional. Indicates stage of the skill. Defaults to development, which is the only supported value for this command.
--profile, -p
Optional. The profile under which the account linking configuration is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

validate-skill subcommand

Executes tests that can be used to validate a skill before submission for certification or at any time during development as regression testing. Refer to Skill Validation API–Supported Validations for supported tests.

The validate-skill command returns a validation-id value which can be used with the get-validation to query the validation results. The low-level validate command combines the validation and retrieval operations in one.

validate-skill command format:

$ ask api validate-skill [-s|--skill-id <skillId>] [-l|--locales <locales>] [-g|--stage <stage>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. The skill ID for the skill you want to validate. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123
--locales, -l
Optional. List of locales. Supported values include: en-US, en-GB, en-CA, en-AU, en-IN. This option is not required if an environment variable named ASK_DEFAULT_DEVICE_LOCALE is set. If this option is not specified and the environment variable ASK_DEFAULT_DEVICE_LOCALE is not set, an error message to specify the environmental variable or the device locale.
--stage, -g
Optional. Indicates stage of the skill. Use development or live as values. Defaults to development.
--profile, -p
Optional. The profile under which the account linking configuration is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

get-validation subcommand

Returns the validation result generated when the validate-skill subcommand is run.

The low-level validate command combines the validation and retrieval operations in one.

get-validation command format:

$ ask api get-validation <-i|--validation-id <validationId>> <-s|--skillId <skillId>> [-p|--profile <profile>] [--debug]

Options:

--validation-id, -i
Required. Validation id for the skill validation request. This is obtained from running the validate-skill subcommand.
--skill-id, -s
Required. The skill ID for the skill you want to validate. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123
--profile, -p
Optional. The profile under which the account linking configuration is obtained. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

submit subcommand

Enables you to submit a skill for certification.

submit command format:

$ ask api submit [-s|--skill-id <skillId>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. 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 created. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

withdraw subcommand

Enables you to withdraw a skill from the certification process. You will be asked to provide a reason for the withdrawal. The choices are:

  • This is a test skill and not meant for certification
  • I want to add more features to the skill
  • I discovered an issue with the skill
  • I haven't received certification feedback yet
  • I do not intend to publish the skill right away
  • Other reason

If you choose other, you can enter more information about the withdrawal.

withdraw command format

$ ask api withdraw [-s|--skill-id <skillId>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
Required. 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 withdrawn. If not included, the default profile is used.
--debug
Optional. Appends a debug message to the standard error.

list-vendors subcommand

Gets the vendor IDs associated with your developer account, and specifies the developer's associated role to the vendor ID.

list-vendors command format:

$ ask api list-vendors [-p|--profile <profile>] [--debug]

Sample output:

[
  {
    "id": "MYVENDORID1234567",
    "name": "Amazon",
    "roles": [
      "ROLE_ADMINISTRATOR"
    ]
  }
]

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.

list-skills subcommand

List the skills for the current profile. The list is returned in JSON format.

list-skills command format:

$ ask api list-skills [-p|--profile <profile>] [--debug]

Sample output:

{
  "skills": [
    {
      "lastUpdated": "2017-07-11T19:29:57.120Z",
      "nameByLocale": {
        "en-US": "example"
      },
      "skillId": "amzn1.ask.skill.6acdbdf8-8420-440e-823e-aaaaaaaabbbb",
      "publicationStatus": "development",
	  "apis": "custom"
    },
    {
      "lastUpdated": "2017-07-05T21:11:16.947Z",
      "nameByLocale": {
        "en-US": "example1"
      },
      "skillId": "amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb",
      "publicationStatus": "development",
	  "apis": "video"	  
    },
    {
      "lastUpdated": "2017-07-05T21:08:03.693Z",
      "nameByLocale": {
        "en-US": "example2"
      },
      "skillId": "amzn1.ask.skill.1e9a668a-1746-451a-b401-aaaaaaaabbbb",
      "publicationStatus": "live",
	  "apis": "music"	  	  
    },
    {
      "lastUpdated": "2017-07-05T17:29:30.046Z",
      "nameByLocale": {
        "en-US": "example3"
      },
      "skillId": "amzn1.ask.skill.2801f509-5e8e-4944-b48d-aaaaaaaabbbb",
      "publicationStatus": "certification",
	  "apis": "flashBriefing"	  	  	  
    }
  ]
}

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.

add-private-distribution-account command format:

ask api add-private-distribution-account <-s|--skill-id <skillId>> --stage live <--account-id <id>>

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Optional. Indicates stage of the skill. Defaults to live, which is the only supported value for this command.
--account-id
Required. Account ARN of the Alexa For Business organization, such as arn:aws:iam::123456789012:root.

delete-private-distribution-account subcommand

Deletes an account from the private distribution list for a specified skill.

delete-private-distribution-account command format:

ask api delete-private-distribution-account <-s|--skill-id <skillId>> --stage live <--account-id <id>>

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Optional. Indicates stage of the skill. Defaults to live, which is the only supported value for this command.
--account-id
Required. Account ARN of the Alexa for Business organization, such as arn:aws:iam::123456789012:root.

list-private-distribution-accounts subcommand

Lists the accounts on a private distribution list for the specified skill.

list-private-distribution-accounts command format:

$ ask api list-private-distribution-accounts <-s|--skill-id <skillId> --stage live

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Optional. Indicates stage of the skill. Defaults to live, which is the only supported value for this command.

enable-skill subcommand

Creates or updates an enablement for the specified skillId and stage.

$ ask api enable-skill <-s|--skill-id <skillId> [-g|--stage <stage>]

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Optional. Indicates stage of the skill. Defaults to development, which is the only supported value for this command.

disable-skill subcommand

Disables an enablement for the specified skillId and stage.

$ ask api disable-skill <-s|--skill-id <skillId> [-g|--stage <stage>]

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Optional. Indicates stage of the skill. Defaults to development, which is the only supported value for this command.

get-skill-enablement subcommand

Checks whether an enablement exist for a given skillId and stage.

$ ask api get-skill-enablement <-s|--skill-id <skillId> [-g|--stage <stage>]

Options:

--skill-id, -s
Required. Skill Id for the target skill.
--stage
Optional. Indicates stage of the skill. Defaults to development, which is the only supported value for this command.

invoke-skill subcommand

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

invoke-skill command format:

$ ask api invoke-skill [-f|--file <file>] [-s|--skill-id <skillId>] [-j|--json <json>] [-e|--endpoint-region <endpoint-region>] [-p|--profile <profile>] [--debug]

Options:

--skill-id, -s
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.

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

simulate-skill subcommand

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

simulate-skill command format:

$ ask api simulate-skill [-f|--file <file>] [-t|--text <text>] [-l|--locale <locale>] [-s|--skill-id <skillId>] [-p|--profile <profile>] [--debug]

Options:

--file, -f
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.

get-simulation command format:

$ ask api get-simulation [-i|--simulation-id <simulation-id>] [-s|--skill-id <skillId>] [-p|--profile <profile>] [--debug]

Options:

--simulation-id, -i
Required. This should be in the format of UUID b8e4ea04-7df3-11e7-bb31-be2e44b06b34.
--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.

intent-requests-history subcommand

Provides skill developers with the aggregated and anonymized transcriptions of user speech data and intent request details for their skills, on a per-skill basis. A skill must have at least 10 unique users per locale in a day, in order for data to be available for that locale for that day. If some locales meet the threshold and other locales do not, data is returned only for those locales that meet the threshold.

$ ask api intent-requests-history <-s|--skill-id <skillId>> [--filters <value>] [--max-results <value>] [--sort-direction <value>] [--sort-field <value>] [--next-token <value>]

To get intent request history for a skill with no filters applied, and no defaults changed, reference the skillId with no other parameters, as shown in the following example.

$ ask api intent-requests-history --skill-id amzn1.ask.skill.12345678-1234-1234-123456789123

Options:

--skill-id, -s
Required. This should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.
--filters
Optional. Filters take the form shown in the following examples.
To get the intent request history for a skill with maximum 100 results in a page:
$ ask api intent-requests-history --skill-id amzn1.ask.skill.12345678-1234-1234-123456789123 --max-results 100

To get the intent request history that is filtered to include only en-US and en-GB locales:

$ ask api intent-requests-history --skill-id amzn1.ask.skill.12345678-1234-1234-123456789123 --filters "Name=locale, Values=en-US,en-GB"

To get intent request history for a skill using multiple filters:

$ ask api intent-requests-history --skill-id amzn1.ask.skill.12345678-1234-1234-123456789123 --filters "Name=locale, Values=en-US,en-GB; Name=intent.name, Values=PlayMusic,StopMusic"

The shorthand syntax is:

Name=string,Values=string,string ...

You can filter by the following parameters.

dialogAct.name - dialogAct.name filter matches the result items where the "dialogAct.name" value matches one of the values in this filter. This filter can have multiple values. This filter is not case-sensitive. These values arise in the context of a multi-turn conversation. For more information about the Dialog directive and multi-turn conversations, see Dialog Interface Reference. (Dialog.ElicitSlot | Dialog.ConfirmSlot | Dialog.ConfirmIntent)

locale - locale filter matches the result items where the locale value matches one of the values in this filter. This filter can have multiple values. This filter is not case-sensitive. (en-US | en-GB | en-IN | en-CA | en-AU | de-DE | fr-FR | ja-JP)

intent.confidence.bin - intent.confidence.bin filter matches the result items where the intent.confidence.bin value matches one of the values in this filter. Note that at runtime, skills do not receive intents with LOW confidence. This filter can have multiple values. This filter is not case-sensitive. (HIGH | MEDIUM | LOW)

stage - stage filter matches the result items where the stage value matches one of the values in this filter. This filter can have multiple values. This filter is not case-sensitive. (live | development)

publicationStatus - publicationStatus filter matches the result items where the publicationStatus value matches one of the values in this filter. This filter can have multiple values. This filter is not case-sensitive. (CERTIFICATION | DEVELOPMENT)

utteranceText - utteranceText filter matches the result items based on a full-text search of utteranceText values. This filter can have multiple values. This filter is not case-sensitive. (Any String)

intent.name - intent.name filter matches the result items where the intent.name values matches one of the values in this filter. This filter can have multiple values. This filter is not case-sensitive. (Any String)

intent.slot.name - intent.slot.name filter matches the results where the intent.slots.slot.name matches one or more of the values in this filter. This filter can have multiple values. This filter is not case-sensitive. (Any String)

interactionType - interactionType filter matches the results where the interactionType value matches one of the value(s) in this filter. This filter can have multiple values. This filter is not case-sensitive. (ONE_SHOT | MODAL)
--max-results
Optional. Maximum number of result items that are given in the response. By default, this number is set to 10. maxResult has an upper limit of 250. Positive integer between 1-250 (inclusive).
--sort-direction
Optional. The order in which sorting is applied. By default, the sorting order is descending. This field is not case-sensitive. (asc | desc)
--sort-field
Optional. Result items are sorted according to the value of the field specified in this attribute. Sorting order is defined in a separate attribute called --sort-direction. This field is not case-sensitive. (dialogAct.name | locale | intent.confidence.bin | stage | intent.name | utteranceText | interactionType | publicationStatus)
--next-token
Optional. nextToken is used to sequentially page through the result items. Use nextToken along with the maxResults parameter to specify how many results should be loaded in the page. To load the first page this property can be set to null. It expires in 60 minutes. This token is bound to the set of filters and the skillId that were used to obtain it, and will be ignored if used with other parameters: the first page of results for the new search parameters will be returned.

util command

The util command provides utility tools to manage Alexa skill development.

Subcommands

Task Subcommand
Generate LWA (Login With Amazon) access_token and refresh_token, which may be needed for use with Alexa developer tools generate-lwa-tokens

generate-lwa-tokens

Generates an LWA access token and refresh token, which may be required by the skill to access Alexa development tools.

To use this feature, you must whitelist a URL following these steps:

  1. Browse to https://developer.amazon.com/home.html.
  2. Select Apps & Services on the top menu bar.
  3. Select Security Profile in the submenu bar.
  4. Pick the profile you want to use and select the Web settings tab. If you do not have a profile, you can create one by clicking Create a New Security Profile and following the instructions.
  5. Click Edit and paste these URLs to Allowed Return URLs: http://127.0.0.1:9090/cb (if using the default option to open a browser) or https://s3.amazonaws.com/ask-cli/response_parser.html (if using the --no-browser option)
  6. Save the change.

generate-lwa-tokens command format

$ ask util generate-lwa-tokens [--scope <scope>] [--no-browser]

Options

--scope
Optional. Request particular scope(s) from the user who will log in to the Alexa developer portal. If the scopes option is not provided, then by default it uses the same scope as ASK CLI does.
--no-browser
Optional. Display authorization URL instead of opening a browser. The developer can then copy the URL displayed in the console and open the link with a web browser on another device to be directed to the login page of Amazon.

In the CLI window, you will then be prompted for the Client ID and Client Secret. Obtain these values from your security profile. To access your security profile, browse to https://developer.amazon.com/home.html, and select Security Profiles. Open your security profile, and copy the Client ID and Client Secret.

When you enter the Client ID and Client Secret, you are prompted to log in to the SMAPI CLI page on Amazon with your developer account. Log in, and the access_token and refresh_token values will appear in the CLI window.

lambda command

The lambda command enables you to retrieve and upload code for an AWS Lambda function.

lambda command format:

$ ask lambda <subcommand> [-f|--function <functionName>] [other options]

Subcommands

Task Subcommand
Download an existing Lambda function download
Upload an existing Lambda function upload
View Cloudwatch logs for a Lambda function log

download subcommand

Downloads code for the specified Lambda function to an optional specified destination.

download command format:

$ ask lambda download [-f|--function <functionName>] [-d|--dest <destPath>]

Options:

--function, -f
Optional. The Lambda function's name. If this option is not set, the download operation will display a list of Lambda functions for the configured account, and you can choose one from a numbered list.
--dest, -d
Optional. Specifies the download destination for the Lambda function. If not set the Lambda is downloaded to the current working directory.

upload subcommand

Uploads files from the current directory or specified directory to a specified Lambda function.

upload command format:

$ ask lambda upload [-f|--function <functionName>] [-s|--src <sourcePath>]

Options:

--function, -f
Required. Specifies the target Lambda function name.
--src, -s
Optional. Specifies the source directory to upload from. If not specified, the contents of the current working directory are uploaded.

log subcommand

Enables you to view the CloudWatch logs for the specified Lambda function.

log command format:

$ ask lambda log [-f|--function ] [--start-time ] [--end-time ] [--limit ] [--raw] </code>

Options:

--function, -f
Required. The Lambda function name.
--start-time
Optional. The start time for the log time range you wish to view. This should be written in the format 1dayago for 1 day ago, or 30hoursago for 30 hours ago. The default is 1dayago.
--end-time
Optional. The end time for the log time range you wish to view. This should be written in the format 1dayago for 1 day ago, or 30hoursago for 30 hours ago.
--limit
Optional. Integer indicating the number of log entries to display.
--raw
Optional. Displays the logs without color or formatting.

Debug Mode for ASK CLI Commands

Almost all of the commands, as shown in their descriptions, can be run in debug mode, by appending --debug to the command.

The same results will appear as when –debug is not specified, except that an additional debug message is displayed (sent to stderr) after the command finishes executing. This debug message consists of these fields:

{timestamp, api-name, requesit-id, method, url, response-code, request-header, request-body, response-header, response-body}

To save these results, run the command and pipe the output to a local text file, as follows:

ask some-command --debug 2> debug.txt

In-Skill Product Command Reference