Getting started with Alexa Skill Kit Command line Interface: ASK CLI
ASK CLI is a tool provided by Amazon which allows you to easily integrate Alexa skills into Amazon web services. If you’re a serious Alexa skill’s developer, knowing this will speedup your development time. This will be a step by step guide from creating a CLI user to deploying changes on AWS Lambda. I hope you enjoy reading this.
Prerequisites
Install Node.js
Before we start on ASK Comand line interface. You need to make sure that the latest version of Node.js is installed on your machine.
Check if you’re system is running Node.js 4.5 or greater version.
node --versionTo install or update your version of Node.js, refer to the Node.js downloads page.
Note: Installing Node.js would take some time depending on your internet connection.
Create Amazon AWS and developer accounts
Next step is to register with Amazon web services and developer portal. To create Amazon accounts, head into https://aws.amazon.com and https://developer.amazon.com.
Note: You may user your existing Amazon account to register as a developer.
Install ASK CLI
We are back on the track. Now it’s time to install the real game changer. Open up a new command line window and enter the following command. This will install the latest ASK CLI onto your machine.
npm install -g ask-cliBefore we move on with ASK CLI, there are few things we need to configure in Amazon IAM portal. Login to your Amazon AWS account by going to https:/aws.amazon.com. Choose “IAM” under “Security, Identity & Compliance”
In here, you need to create a user with deployment access to AWS Lambda. We will be using this user to configure our ASK_CLI instance.
Create a CLI user in AWS IAM
Before we create a user we need to specify what type of accesses we need our CLI user to contain. It’s always a best practice to grant limited access to your users. Let’s head into “Policies” tab and choose “Create policy” option.
Select “JSON” tab and copy-paste the following JSON configurations. Following configurations enables user to create roles, lambda functions etc.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:GetRole",
"iam:AttachRolePolicy",
"iam:PassRole"
],
"Resource": "arn:aws:iam::*:role/ask-*"
},
{
"Effect": "Allow",
"Action": [
"lambda:AddPermission",
"lambda:CreateFunction",
"lambda:GetFunction",
"lambda:UpdateFunctionCode",
"lambda:ListFunctions"
],
"Resource": "arn:aws:lambda:*:*:function:ask-*"
},
{
"Effect": "Allow",
"Action": [
"logs:FilterLogEvents",
"logs:getLogEvents",
"logs:describeLogStreams"
],
"Resource": "arn:aws:logs:*:*:log-group:/aws/lambda/ask-*"
}
]
}
Once everything is in place. You can select “Review policy” option. This will navigate to a screen where you can give a valid name and description to the policy. Go ahead and choose “Create policy”.
If everything is good. You will be navigated back to the “Policies” screen. You should be able to find the newly created policy in the policies table.
Now we need to attach the policy into a “Group”. Select “Groups” from the IAM pannel and choose “Create New Group” option.
Give a group name you like. Groups can contain multiple policies of choice. However, We will only be including one policy for the sake of this tutorial.
After giving a proper name, go to the next step. In here, you need to specify the policies. Set the “Filer” to “Customer managed”. This option will list all the policies managed by you.
Select the policy you created from the list and go to the final step. You can review the changes made in here. If everything is alright, Select “Create group” option. This will take you back to “Groups” screen. Make sure that the newly created group shows up on the group list.
Now we are heading into the final step of this section. That’s to create a CLI user.
Select the “User” option from the IAM pannel and choose “Add user” option. In the following screen, give a User name and set “AWS Access Type” as “Programmatic access”. Since we will be using this user to mainly login through the command line interface we can opt-out “AWS Management Console access” option. Then click on “Next: permissions” option.
In Permissions screen, Set “Add user to group” option and select the group you have just created. Then click on the “Review” option to validate the settings you have chosen to create the user.
If everything is showing as planned, go ahead and create a user. In the following screen, AWS will generate a “Access key Id” and “Secrect access key” for the user. Copy and paste those keys in a safe place only you have access to. We will later be using those keys to login through the command line interface.
Close the screen and check whether the newly created user account is visible on the user list.
Configure AWS CLI on the computer
Now that we have created the user. We need to tell AWS CLI to use the created user. Open a new command line window and enter the following commands.
Open the aws credentials file.
sudo nano ~/.aws/credentialsNote: If you’re a windows user, this directory will be at %USERPROFILE\.aws\ path.Inside this folder there will be a text file named “credentials”. If that file doesn’t exist, use your favourite text editor to create a credentials file inside .aws directory.
Add the following lines to the credentials file and save it.
[<CLI_USER_NAME>]aws_access_key_id=<aws_access_key_id_value>aws_secret_access_key=<aws_secret_access_key_value>
In here,
<CLI_USER_NAME> : This is the username of the IAM user you have just created. This will be called as the profile name here after.
Note: If there are multiple profiles in the credentials file, Instead of using the “CLI_USER_NAME” you can set it as “[default]”. Then ASK CLI will always use the default profile unless instructed to use a differnt profile.
<aws_access_key_id_value> and <aws_secrect_access_key_value>: These are the two access key values you have previously saved from “Create user” screen.
Now we need to test whether our user credentials are working without any issues. Go back to the command line window and enter the following command. You will be taken to AWS login page. Use your AWS developer credentials to successfully authenticate.
ask init -p <CLI_USER_NAME>When you’re asked to choose the AWS profiles for skill’s Lambda function deployment. Select your profile name and press enter.
If the authentication process is successful, you will see the following output on the comand line interface.
rajeeva$ ask init -p ASK_CLI_TEST-------------------- Initialize CLI --------------------
Setting up ask profile: [ASK_CLI_TEST]? Please choose one from the following AWS profiles for skill's Lambda functiondeployment.ASK_CLI_TESTSwitch to 'Login with Amazon' page...Tokens fetched and recorded in ask-cli config.Vendor ID set as S1R46DGT7H7816Profile [ASK_CLI_TEST] initialized successfully.
Congratulations! You have successfully configured ASK CLI.
Now what’s left is to create a new Alexa Skill and deploy it to AWS Lambda instance programmatically using ASK CLI.
Create, Update and Deploy Alexa Skill using ASK CLI
In this section, we will use ASK CLI functions to create and deploy changes to AWS.
Let’s create a new Alexa skill. Open a command line window and navigate to a desired location you would like to save your skill’s source files. Then enter the following command.
ask new? Please type in your new skill name:
Test Skill
New project for Alexa skill created.
Note: If you received any errors related to profiles etc. Mention the profile name explicitly by using the following command. ask new -p <cli_user_profile>
Open the folder in Finder (or Windows explore if you’re on a PC). You should see a folder with the name of your skill and containing the following folder structure.
Let’s take a look at the important files in here.
skill.json : This file contains all the configurations of your Alexa skill. You can use this file to change the name of the skill, add samples , change icon image, set Lambda function etc.
models/en-US.json : This is the interaction model file of your skill. You can use this file to add/edit intents, define slots add utterance, change the invocation name etc.
lambda/custom/index.js : This file contains the business logic of your skill. You can define new intents or commit changes to your existing logic.
Let’s do some changes to our index.js file and deploy the changes to AWS.
Add the following line of code inside the ‘LaunchIntent’ function in Index.js file.
this.emit(':tell','Hello World from ASK CLI');This should say ‘Hello world from ASK CLI’ whenever we invoke our skill.
Enter the follwoing command inorder to deploy the latest changes to AWS.
ask deployNote: This operation may take a few mintues to complete depending on your internet connection speeds. In case you see the following error “You do not have access to the resource”. Mention the profile name explicitly when entering the command.
In case ask deploy returns the following error “ResourceConflictException: Function already exist: ask-custom-Test_Skill-default”. Clone the skill using the skill id and deploy once again. You can clone a skill using this command.
ask clone -s <skill_id> -p <cli_user_profile>
This will create a new skill in Alexa developer console and a new Lambda function in the AWS console. You will see the following output on the command line window if the deployment is successful.
Skill Id: amzn1.ask.skill.ecaa7b96-0718-4abf-a69e-eaaea31b50da
Skill deployment finished.
Model deployment finished.
Lambda deployment finished.Now login to your Alexa developer console by going to http://developer.amazon.com. Select “Alexa” from the dashboard and choose “Alexa skills kit”.
Viola! Your shiny new Alexa skill is there.
Now login to AWS developer console and select “Lambda” under the “Compute” sub topic.
Hooray! Check out your brand new Lambda function.
Cloning an existing skill through ASK CLI
If you’re a seasoned Alexa developer, chances are that you already have a bunch of skills in your Alexa developer arsenal. ASK CLI provides a friendly interface to clone an existing skill.
Go back to your Alexa developer console and copy the “skill id” of the skill you need to clone. After that use the following comand line function to clone the skill onto your local machine.
ask clone -s <skill_id> -p <cli_user_profile>You can use “ask deploy” to deploy changes to AWS later.
Note: AWS would create a seperate Alexa skill or a Lambda function if the cloned skill wasn’t created from the same IAM user profile that’s used to deploy it.
Update the local repository with the changes made to the interaction model from the developer console
Sometimes it would be easier to do changes to the interaction model through the Alexa developer console. In scenarios like this, you need to make sure that the changes are in sync with the local copy. Otherwise the changes in the local copy will override the recent changes made from the developer console when it’s deployed through ASK CLI.
Note: Make sure you save and build the model before fetching the latest changes using the following command.
ask api get-model -s <skill_id> -p <cli_user_profile> -l en-US > models/en-US.jsonUpdate the local repository with the changes made to the skill configuration from the developer console
As described previously, If you change the name of the skill, icon or add additional test samples from the developer console. Those changes need to be in synced with the local repository. Use the following command to apply latest changes on to the local skill.json file.
ask api get-skill -s <skill_id> > skill.jsonASK CLI has better segmentation between the Alexa skill and AWS Lambda function. Which means you could update either Interaction model or the Lambda function depending on which file you have made the changes.
For example, You have only changed a slot name in the models/en-US.json file. Deploying everything would be an expensive and a time consuming task for a small change like this. In such type of situations, we can use ASK CLI sub commands to only update the parts of the skill. Use the following command to only update the only model file.
ask api update-model -s <skill_id> -p <cli_user_profile> -l en-US -f models/en-US.jsonNote: For full details of the ASK API functions and sub commands use the following URL. https://developer.amazon.com/docs/smapi/ask-cli-command-reference.html
Testing your Alexa skill without a device
If you’re constantly working on Alexa skill projects, It will not be feasible to always talk to Amzon Eco device. You will understand it when you frequently run into bugs in your code and want to talk to Alexa to verify the flow each time a bug is fixed. Luckily, Amazon has got our backs. In this section, We will use our skill as a chatbot to test skill flows. To start, login into your Amazon developer portal and goto Alexa developer console. Select Alexa skill kit and choose your skill from the skill list.
Once you open the skill you need to test, Select “Test” option from the options panel to the left side of the screen.
Check whether the skill is enabled for testing. Now, choose “Go to Test Simulator” option to start testing the skill.
In the Text field on the following screen, Type “open <invocationName>”.
Note: To find and update the “invocationName”, go to models/en-US.json in the local repository.
That’s all! If you have a Amazon Eco or any other Alexa enabled device, go to https://alexa.amazon.com then login to your device using your Amazon developer account. You will find your skill at Skill -> Your Skill -> Dev Skills
I hope you find this article useful. Happy coding!
