ASK CLI Command Reference, v0

Note: Sign in to the developer console to build or publish your skill.

This reference describes all commands available through ASK CLI version 0. For an overview of ASK CLI, see ASK CLI Overview. To get started with the Alexa Skills Kit Command Line Interface (ASK CLI), see the ASK CLI Quick Start.

Warning: You are viewing the ASK CLI v0 documentation. The current version of the ASK CLI is Version 2. Switch to v2 to view the latest documentation.

ASK CLI Commands

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.	`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`
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`.	`ask simulate`
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]`

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] [--debug]

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.

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

-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 cli_config file contains per-profile deployment settings like skillid.

new command format:

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

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

deploy command

Deploys a skill project to your developer account, optionally deploying AWS Lambda code.

If you are using AWS Lambda to host your skill service, then the following applies:

For a custom skill, your skill.json file, interaction model file, and AWS Lambda function code files will be deployed.
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 fails.

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 updates 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:

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

Deploying it will change it to this format:

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

deploy command format:

ask deploy [--no-wait] [--target <target>] [-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.
--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.

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

simulate command format:

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

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 details about the interaction model description, see Interaction Model Schema.

api command format:

$ ask api <subcommand>

Subcommands

Task	Subcommand
Create a new skill	create-skill
Get a skill	get-skill
Delete a skill	delete-skill
Update the skill configuration details	update-skill
Get an interaction model for skill	get-model
Update a model, or create a new interaction model for skill. A build of the model is triggered.	update-model
Get the model status of an interaction model	get-model-status
Get status of a skill after create/update call	get-skill-status
Get the ETag associated with an interaction model	head-model
Add or update account linking configuration information for a skill associated with your developer account	create-account-linking
Get account linking configuration information for a skill	get-account-linking
Submit a skill for certification	submit
Withdraw a skill from the certification process	withdraw
Get the vendor IDs associated with your developer account	list-vendors
List skills for a vendor	list-skills
Invoke a skill	invoke-skill
Simulate a skill	simulate-skill
Get simulation result	get-simulation

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} > skill.json

get-skill command format:

$ ask api get-skill [-s|--skill-id <skillId>] [-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.
--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 subcommand

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

delete 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 schema provided with the --file option.

update-skill command format:

$ ask api update-skill [-s|--skill-id <skillId>] [-f|--file <fileName>] [-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.
--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} -l {locale} > model.json

get-model command format:

$ ask api get-model [-s|--skill-id <skillId>] [-l|--locale <locale>] [-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: Required. Locale for the target model. Valid values are en-US, en-GB or de-DE. If not specified, you will be prompted to enter the locale.
--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>] [--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: Required. Locale for the target model. Valid values are en-US, en-GB or de-DE. If not specified, you will be prompted to enter the locale.
--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-model-status subcommand

Retrieves the build status of the specified model.

get-model-status command format:

$ ask api get-model-status [-s|--skill-id <skillId>] [-l|--locale <locale>] [-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.
--locale, -l: Required. Locale for the target model. Valid values are en-US, en-GB or de-DE. If not specified, you will be prompted to enter the locale.
--profile, -p: Optional. The profile under which the build status is retrieved. If not included, the default profile is used.
--debug: Optional. Appends a debug message to the standard error.

get-skill-status subcommand

Retrieves the skill status.

get-skill-status command format:

$ ask api get-skill-status [-s|--skill-id <skillId>] [-l|--locale <locale>] [-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.
--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>] [-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: Required Locale for the target model. Valid values are en-US, en-GB or de-DE. If not specified, you will be prompted to enter the locale.
--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 Linking an Alexa User with a User in Your System 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>] [-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.
--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>] [-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
--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"
    },
    {
      "lastUpdated": "2017-07-05T21:11:16.947Z",
      "nameByLocale": {
        "en-US": "example1"
      },
      "skillId": "amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb"
    },
    {
      "lastUpdated": "2017-07-05T21:08:03.693Z",
      "nameByLocale": {
        "en-US": "example2"
      },
      "skillId": "amzn1.ask.skill.1e9a668a-1746-451a-b401-aaaaaaaabbbb"
    },
    {
      "lastUpdated": "2017-07-05T17:29:30.046Z",
      "nameByLocale": {
        "en-US": "example3"
      },
      "skillId": "amzn1.ask.skill.2801f509-5e8e-4944-b48d-aaaaaaaabbbb"
    }
  ]
}

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.

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:

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. </dd>
--profile, -p: Optional. To use a profile other than the default, include the profile name.

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

Was this page helpful?

Provide feedback

Last updated: Aug 08, 2024

ASK CLI Command Reference, v0

ASK CLI Commands

init command

new command

deploy command

clone command

simulate command

api command

create-skill subcommand

get-skill subcommand

delete subcommand

update-skill subcommand

get-model subcommand

update-model subcommand

get-model-status subcommand

get-skill-status subcommand

head-model subcommand

create-account-linking subcommand

get-account-linking subcommand

submit subcommand

withdraw subcommand

list-vendors subcommand

list-skills subcommand

invoke-skill subcommand

simulate-skill subcommand

get-simulation subcommand

lambda command

download subcommand

upload subcommand

log subcommand

Debug Mode for ASK CLI Commands

Was this page helpful?