ASK CLI Reference for In-Skill Purchasing

The ASK CLI provides several commands for manipulating in-skill products.

Overview

When you work with in-skill products, you can choose from the following types of commands:

  • High-level commands that perform several actions with one command and simplify working with in-skill products. These commands modify the deploy status and update the skill configuration file.

  • Low-level commands to control individual parts of your in-skill products. Note that the low-level commands do not modify the deploy status or the skill configuration file.

The general syntax for the ASK CLI is:

$ ask <command> <subcommand> [options]

When you manage products with the ASK CLI you will make changes in local copies of your skill files. These changes take effect when you deploy the updated skill and products to your developer account.

Following is a list of high-level and low-level tasks for in-skill products and their commands.

Task Command or Subcommand
Add a new in-skill product to a skill add isp
Remove an in-skill product from a skill remove isp
Deploy an in-skill product to the developer account deploy
Get the status of a product status
Get the in-skill product file or summary by product ID. get-isp
Create a new product using a product JSON file create-isp
Update an existing product by specifying a product JSON file update-isp
Associate a specified product to a specified skill associate-isp
Disassociate a specified product from a specified skill disassociate-isp
Delete a product with the specified product ID. delete-isp
Get a list of products associated with a specified vendor ID list-isp-for-vendor
Get a list of products associated with a specified skill ID list-isp-for-skill
Get the skills associated with a specified product. list-skills-for-isp
Reset an in-skill product purchase (entitlement). reset-isp-entitlement

For commands to manipulate skills, see ASK CLI Command Reference

For an introduction to using the ASK CLI with products, see Use the ASK CLI to Manage In-Skill Products.

High-level commands

There are high-level commands that perform multiple operations for in-skill products.

add isp

Similar to the git add, the add command marks an in-skill product as Add, so it can be added and/or associated with the skill when deployed. You can view the status of the product with the status command.

add isp command format:

$ ask add isp [-i| --isp-id <ispId>] [-n| --isp-name <ispName>] [-f| --file <filePath>] [-p| --profile <profile>]

There are three approaches to add an in-skill product to current skill project:

  • Add by template: ask add isp This is the default and recommended approach to add an in-skill product. You are prompted to choose a product type and then a product template. You will also be prompted to input a name. This name specifies the referenceName of the skill and cannot contain spaces. The name you specify also replaces the default file name.
    The template is saved to template_name/input_name.json under the skillProjectPath/isps/productType folder.
  • Add by file: ask add isp --file <filePath> Specify a relative or absolute path to an existing in-skill product file. The –file option adds the specified file to the skill configuration in the Add status, so it can be deployed to a developer account with the skill.
  • Add by product ID: ask add isp --isp-id <ispId> Specify a product ID for an existing (deployed) product that is not associated with the current skill. This will add the in-skill product to the skill configuration file and it will be associated with a skill when it's deployed to the developer account.

Options:

--file, -f <filePath>

Optional. Add an in-skill product at the specified path to the skill project. This command validates whether the file path points to a correctly formatted JSON file. If this in-skill product is marked as Remove, this command can be used stop the removal.

--isp-id, -i <ispId>

Optional. Add an existing in-skill product with the specified product ID to the skill project. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123. The ASK CLI associates the in-skill product to the current skill and downloads the product file when deployed. If this in-skill product is marked as Remove, this command can be used stop the removal.

--isp-name, -n <ispName>

Optional. The name to assign to in-skill product when creating in-skill product using template. When ` –isp-name` is omitted, ASK CLI provides a prompt for specifying the in-skill product name.

--profile, -p

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


remove isp

Removes an in-skill product from the skill project, and the removed in-skill product can be deployed to the developer account. You should only remove a product if the associated skill is in the development stage, or the product has not been purchased by any users.

remove isp command format:

$ ask remove isp [-i| --isp-id <ispId>] [-f| --file <filePath>] [-p| --profile <profile>]

There are two options to remove an in-skill product from the current skill project:

-Remove by file ask remove isp --file <filePath> Use if the in-skill product file has already been added or associated to the current skill project and you want to remove it from the from the skill project. The skill will be updated when deployed to the developer account.

-Remove by product ID ask remove isp --isp-id <ispId> Specify a product ID for an existing (deployed) product that you want to disassociate from the current skill. The skill will be updated when deployed to the developer account.

Options:

--file, -f <filePath>

Optional. : File path to the product JSON file. Can be an absolute or relative path. Validation occurs to ensure the path points to a correctly formatted JSON file, and checks whether the file has already been associated or added to current skill project. If the in-skill product file has been associated with current skill, the CLI disassociates it from the skill and removes the product file when the skill is deployed. If the in-skill product status is Add or Associate, this command can be used to reverse the operation.

--isp-id, -i <ispId>

Optional. Product Id for the the existing product is to be removed. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123. The ASK CLI disassociates the in-skill product from the current skill and deletes the product file when the skill is deployed. If the in-skill product status is Add, this command can be used to reverse the add operation.

--profile, -p

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


deploy

You deploy a product by deploying the skill it is associated with. For full details on deploying skills, see the CLI command reference. When you deploy a skill, products are added, removed or updated. Use the status command to check a product's status.
When you have successfully deployed a product to the current skill, the status of the product will be Update.


status

You can get the deploy status of products that have been manipulated with high-level commands (Add, Remove) by using the following command:

$ ask status --isp

This command displays the current deployment status of in-skill products for this current skill. It displays:

  • Error messages if there are invalid products settings in the skill configuration file (.ask/config)
  • Purchasable and non-purchasable products and their deploy status
  • Untracked product files under the CurrentSkillProjectDirectory/isps

A product can have the following statuses :

  • Add, which means the the product is new and will be associated to the current skill during deployment. When a product is created and successfully deployed, the product is then marked as Update. If skill association fails, it is marked as Associate and the CLI will try to associate to skill in the next deploy.
  • Remove, which means the CLI will disassociate the product from the skill during deployment. If the remove operation succeeds, the product is removed from .ask/config and the isps folder, otherwise the status is unchanged.
  • Associate, which means the CLI associates the product to the skill during deployment.
  • Update, which means the product has been previously deployed to this skill, and during the next deployment, the CLI updates the product using files in the isps folder.

Following is an example status output.

Purchasable in-skill product(s) to be deployed:
    (use "ask add isp --file <filePath>/--isp-id <id>" to add in-skill product to current skill)
    (use "ask remove isp --file <filePath>/--isp-id <id>" to remove in-skill product from current skill)

DEPLOY STATUS | ID                                      | FILE                
Add           | N/A                                     | isps/entitlement/pack1.json      
Associate     | amzn1.adg.product.0dc13545-bb0c-4134-b6 | isps/entitlement/pack2.json      
Update        | amzn1.adg.product.92fef67c-2da3-4799-a0 | isps/subscription/all_access_pack.json
Remove        | amzn1.adg.product.615016b3-eb06-4ed3-920| isps/entitlement/space_pack.json
Update        | amzn1.adg.product.80fe96ae-627d-43c8-69 | isps/consumable/five_hint_pack.json

Low-level commands

In addition to the high-level commands listed previously, you can also access commands that enable you to query and manage in-skill products independent of a skill project. These commands do not modify the deploy status or the skill configuration file.

ask api command format:

$ ask api <subcommand>

Task Subcommand
Get the in-skill product file or summary by product ID. get-isp
Create a new product using a product JSON file create-isp
Update an existing product by specifying a product JSON file update-isp
Associate a specified product to a specified skill associate-isp
Disassociate a specified product from a specified skill disassociate-isp
Delete a product with the specified product ID. delete-isp
Get a list of products associated with a specified vendor ID list-isp-for-vendor
Get a list of products associated with a specified skill ID list-isp-for-skill
Get the skills associated with a specified product. list-skills-for-isp
Reset an in-skill product purchase (entitlement). reset-isp-entitlement

get-isp

Gets the product file for a specified product ID.

get-isp command format:

$ ask api get-isp <-i|--isp-id <isp-id>> <-g|--stage <stage> [--summary] [-p|--profile <profile>] [--debug]

Options:

--isp-id | -i
Required. The in-skill product ID. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123.
--stage | -g
Required. The stage of the in-skill product; either development or live.
--summary
Optional. Return the product summary instead of the product.
--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.

Back to Low-Level Commands


create-isp

Creates a new in-skill product with the specified JSON product file.

create-isp command format:

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

Options:

--file | -f

Required. File path to the product file in JSON format. Can be an absolute or relative path.

--profile | -p

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

--debug

Optional. Appends a debug message to the standard error.

Back to Low-Level Commands


update-isp

Updates the in-skill product for the specified productId. You can only update in-skill products in the development stage.

update-isp command format:

$ ask api update-isp <-i|--isp-id <isp-id>> <-f|--file <fileName>> [-g|--stage <stage>] [-p|--profile <profile>] [-e|--etag <ETag>] [--debug]

Options:

--isp-id | -i
Required. Product ID for the the product is to be updated. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123.
--file | -f
Required. File path to the product file in JSON format. Can be an absolute or relative path.
--stage | -g
Optional. The stage of the in-skill product. Must be development.
--profile | -p
Optional. The profile under which the product is created. If not specified, the default profile is used.
--etag | -e
Optional. The ETag is a unique identifier for a version of a resource. If ETag is provided in a product update, the server will update the resource only if the version didn't change.
--debug
Optional. Appends a debug message to the standard error.

Back to Low-Level Commands


associate-isp

Associates an in-skill product with a skill.

associate-isp command format:

$ ask api associate-isp <-i|--isp-id <isp-id>> <-s|--skill-id <skill-id>> [-p|--profile <profile>] [--debug]

Options:

--isp-id | -i

Required. Product ID to be associated to a skill. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123.

--skill-id | -s

Required. Skill ID that the product is associated to. The ID should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--profile | -p

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

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

Back to Low-Level Commands


disassociate-isp

Removes the association between an in-skill product and a skill. Note that you should only disassociate a product if the skill is in the development stage, or the product has not been purchases by any users.

disassociate-isp command format:

$ ask api disassociate-isp <-i|--isp-id <isp-id>> <-s|--skill-id <skill-id>> [-p|--profile <profile>] [--debug]

Options:

--isp-id | -i

Required. Product ID to be disassociated to a skill. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123

--skill-id | -s

Required. Skill ID that the product is disassociated from. The ID should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--profile | -p

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

--debug

Optional. Appends a debug message to the standard error.

Back to Low-Level Commands


delete-isp

Deletes an in-skill product. You can only use this command with products that have never been associated with a live skill, or if the product has never been purchased by a user.

delete-isp command format: ` $ ask api delete-isp <-i|--isp-id <isp-id>> [-p|--profile <profile>] [-g|--stage [stage]] [-e|--etag <ETag>] [--debug]

Options:

--isp-id | -i

Required. Product ID to be deleted. The ID should be in the format amzn1.adg.product.12345678-1234-1234-123456789123.

--profile | -p

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

--stage | -g

Optional. The stage of the in-skill product. Must be development.

--etag | -e

Optional. The ETag is a unique identifier for a version of a resource. If ETag is provided in a product update, the server will update the resource only if the version didn't change.

–debug

Optional. Appends a debug message to the standard error.

Back to Low-Level Commands


list-isp-for-vendor

Lists the products associated with the specified vendor ID

list-isp-for-vendor command format:

$ ask api list-isp-for-vendor <--vendor-id <vendorId>> [-p|--profile <profile>] [-r|--reference-name <referenceName>] [-i|--isp-id-list <ispIdList>] [-t|--type <type>] [-g|--stage <stage>] [-u|--status <status>] [--isAssociatedWithSkill <isAssociatedWithSkill>] [--max-items <maxItems>] [--starting-token <startingToken>] [--debug]

Options:

--vendor-id

Required. The vendor ID under which the in-skill-products are created.

--profile | -p

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

--reference-name | -r

Optional. Filter in-skill products by the reference name.

--type | -t

Optional. Filter the returned products by type, either ENTITLEMENT or SUBSCRIPTION.

--stage | -g

Optional. The stage of the in-skill product; either development or live.

--status | -u

Optional. Filter the returned products by status such as Add or Update.

--isAssociatedWithSkill| -k

Optional. Filter in-skill products by whether the in-skill product is associated with any skill. Valid values are ASSOCIATED_WITH_SKILL or NOT_ASSOCIATED_WITH_SKILL.

--max-items <maxItems>

Optional. The total number of items to return in the command's output. If the total number of items available is more than the value specified, a nextToken is provided in the command's output. To resume pagination, provide the nextToken value in the starting-token argument of a subsequent command.

--starting-token

Optional. A token to specify where to start paginating. This is the next-token from a previously truncated response.

--debug

Optional. Appends a debug message to the standard error.

Back to Low-Level Commands


list-isp-for-skill

Gets a list of in-skill products associated with a skill.

list-isp-for-skill command format:

$ ask api list-isp-for-skill <-s|--skill-id <skill-id> <-g|--stage <stage> [-p|--profile <profile>] [--debug]

Options:

--skill-id | -s

Required. Skill ID to get in-skill products for. The ID should be in the format amzn1.ask.skill.12345678-1234-1234-123456789123.

--stage | -g

Required. The stage of the in-skill product; either development or live.

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

Back to Low-Level Commands


list-skills-for-isp

Get a list of skills associated with the in-skill product.

list-skills-for-isp command format:

$ ask api list-skills-for-isp <-i|--isp-id <isp-id>> <-g|--stage <stage> [-p|--profile <profile>] [--debug]

Options:

--isp-id | -i

Required. The in-skill product ID.

--stage | -g

Required. Stage for in-skill product.

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

Back to Low-Level Commands


reset-isp-entitlement

Reset whether an in-skill product (entitlement, subscription, or consumable) shows as purchased for a profile. Use this function when an in-skill product is in the development stage, for testing purposes. When you purchase a product with the developer account the skill is associated with, you can purchase products multiple times and reset the purchase using the reset-isp-entitlement API and the developer account is not charged for the purchase.

This command makes the following updates to the specified product:

  • Resets entitled to NOT_ENTITLED.
  • Resets purchasable to PURCHASABLE
  • Resets activeEntitlementCount to 0

reset-isp-entitlement command format:

$ ask api reset-isp-entitlement <-i|--isp-id <isp-id>> <-g|--stage <stage>> [-p|--profile <profile>] [--debug]

Options:

--isp-id | -i

Required. The in-skill product ID.

--stage | -g

Required. The stage of the in-skill product. Must be development.

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

Back to Low-Level Commands