ask-cli/docs/concepts/Alexa-Hosted-Skill-Commands.md

Alexa Skills Kit (ASK) Command Line Interfaces

# CREATE SKILL - NEW COMMAND

`ask new` creates an [Alexa hosted skill](https://developer.amazon.com/en-US/docs/alexa/hosted-skills/build-a-skill-end-to-end-using-an-alexa-hosted-skill.html), clones the skill project, and provides a git-ready environment on the local machine. This replaces the `ask create-hosted-skill` command in CLI v1.

Using `ask new`, the Alexa hosted skill service will create a new AWS account, which owns a Git repository using AWS CodeCommit, and an AWS Lambda function centered back-end. This allows developers to either code on the portal editor or checkout the code using Git and code on local IDEs.

**STRUCTURE OF NEW COMMAND:**

`ask new [-p | --profile <profile>] [--debug] [-h | --help]`

**OPTIONS DESCRIPTION:**

**profile**: Optional. Profile name to be used. Uses `default` as the default profile name, if this option or the environmental variable `ASK_DEFAULT_PROFILE` is not set.

**debug**: Optional. Show debug messages.



## WORKFLOW:

Users will be asked the following questions to create a new skill:

* Prompts user for `programming language`
	* Select programming language
	* AHS supports Python3.7 and Node10.x
* Prompts user for a method to host your skill's backend resources
	* Select `Alexa-hosted skills`
* Prompts user for `skill name`
 	 * Leave empty to use the default skill name  `Hello World Skill`
* Prompts user for a `folder name` for the skill project
 	 * Leave empty to use the default folder name  `HelloWorldSkill`

The user is not prompted for a `skill template`. The [Hello World Skill](https://github.com/alexa/skill-sample-nodejs-hello-world) is the only option for now.



# DOWNLOAD SKILL - INIT COMMAND

`ask init --hosted-skill-id <hosted-skill-id>` -- download an existing Alexa-Hosted Skill to their local environment.

This command initializes Alexa Hosted Skills by cloning the project from the hosted skill service, downloading the latest Alexa skill package, and provide a git-ready environment. Developers can then checkout, pull from, and push to a remote Git repository from their local machines.


**STRUCTURE OF INIT COMMAND:**

`ask init [--hosted-skill-id <hosted-skill-id>] [-p | --profile <profile>] [--debug] [-h | --help]`

**OPTIONS DESCRIPTION:**

**hosted-skill-id**: Required. Skill-id for the Alexa hosted skill.

**profile**: Optional. Profile name to be used. Uses `default` as the default profile name, if this option or the environmental variable `ASK_DEFAULT_PROFILE` is not set.

**debug**: Optional. Show debug messages.



## GIT CREDENTIALS

To access the CodeCommit repository, the Alexa hosted service uses git-credential along with ASK-CLI and SMAPI to automatically pass down temporary Git credentials.

Using `ask util git-credentials-helper` in the skill root directory can retrieve the username and password of the Git credentials.



# UPGRADE PROJECT - UPGRADE COMMANDS

Skills created with CLI 1.x will need to update their project structure in order to deploy with the CLI v2.
`ask util upgrade-project` command will attempt to perform the necessary changes.

**STRUCTURE OF UPGRADE COMMAND:**

`ask util upgrade-project [-p | --profile <profile>] [--debug] [-h | --help]`

**OPTIONS DESCRIPTION:**

**profile**: Optional. Profile name to be used. Uses `default` as the default profile name, if this option or the environmental variable `ASK_DEFAULT_PROFILE` is not set.

**debug**: Optional. Show debug messages.


## UPGRADE STEPS:
1. Using ask-cli 1.x, deploy your skill:
	* `$ ask deploy`
2. Install ask-cli:
	* `$ npm install -g ask-cli`
3. Upgrade your skill project with ask-cli. From your project's root directory, run:
	* `$ ask util upgrade-project`
    * A hidden folder named ./legacy contains a copy of your v1 skill project.
    * The CLI v2 skill-package directory is downloaded to the working directory.
    * The CLI v2 ask-resources.json will be generated.
    * The dev branch is merged into the master branch. The dev branch is then removed.
4. Commit upgrade changes:
  * `$ git commit -m "upgrade project for CLI v2"`



# DEPLOY SKILL - GIT PUSH

`$ git push` deploys skill package resources and skill code.
Unlike in CLI v1, running `ask deploy` on hosted skills will no longer trigger skill deployment in CLI v2.
Instead, `$ git push` sends the latest source code to Lambda.  It also deploys skill-package changes such as the interaction model, skill manifest and in-skill products.

## DEPLOYMENT STEPS:
* Push to deploy skill code and reosurces:
	* `$ git push`
  * Pushing in `master` branch deploys "lambda" folder to user's `development` stage AWS Lambda function, and deploys "skill-package" folder as skill's JSON files
  * Pushing in `prod` branch deploys "lambda" folder to user's `live` stage AWS Lambda function, and deploys "skill-package" folder as skill's JSON files


## Git Pre-push Hook

CLI v2 supports Alexa Hosted skill, a git-native service, to track deployment states using the pre-push hook. When $ git push executes, the pre-push hook prints the skill portal URL to allow users to track deployment states.