Merge pull request #46 from electricimp/develop

v2.4.0

Author: Pavel Petroshenko

Diff for: CommandsManual.md

@@ -2,6 +2,9 @@
 
 ## List Of Commands ##
 
+**[impt account info](#account-info)**<br />
+**[impt account list](#account-list)**<br />
+
 **[impt auth info](#auth-info)**<br />
 **[impt auth login](#auth-login)**<br />
 **[impt auth logout](#auth-logout)**<br />
@@ -72,6 +75,7 @@
 
 - [Command Syntax](#command-syntax)
 - [The Help Option](#the-help-option)
+- [The Version Option](#the-version-option)
 - [Command Output](#command-output)
 - [Entity Identification](#entity-identification)
 - [Device Group Type](#device-group-type)
@@ -116,6 +120,10 @@ The `--help` option (alias: `-h`) can be used with a fully or a partially specif
 - `impt <command_group> --help` &mdash; Displays a list of all of the group’s commands.
 - `impt <command_group> <command_name> --help` &mdash; Displays a detailed description of the command.
 
+## The Version Option ##
+
+- `impt --version` or `impt -v` &mdash; Displays the version of *impt*.
+
 ## Command Output ##
 
 The `--output <mode>` option (alias: `-z`) can be used to adjust the output generated by a command. If the option is not specified, the default verbose output is generated.
@@ -130,46 +138,50 @@ The `--output` option has the following `<mode>` values:
 
 ## Entity Identification ##
 
-Applicable to the following impCentral API entities &mdash; Account, Product, Device Group, Device and Deployment &mdash; these rules govern how *impt* searches an entity:
+For the impCentral API entities described in this section &mdash; Account, Product, Device Group, Device and Deployment &mdash; *impt* obeys the following rules when searching one of these entities:
 
-- There is an order of attributes for every entity type (see below).
-- *impt* starts from the first attribute in the order and searches the specified value for this attribute.
+- *impt* defines a specific order of attributes for every entity type (described in the subsections below).
+- Some of the entity types additionally support hierarchical identifiers (described in the subsections below).
+- If an entity type supports a hierarchical identifier and the specified value matches the hierarchical identifier pattern, *impt* searches the entity by parsing the hierarchical identifier. If only one entity is found, the search is stopped.
+- Otherwise, *impt* starts from the first attribute in the list of the entity type's supported attributes and searches the specified value for this attribute.
 - If no entity is found for this attribute, the tool searches the specified value for the next attribute in the order.
 - If at least one entity is found for the particular attribute, the search is stopped.
 - If no entity is found for all attributes, or more than one entity is found, then, depending on a particular command, that may be considered as a success (for all `list` commands) or as a fail (for all other commands).
 
-### Account Identifier ###
+An Entity Identifier must not be empty.
 
-Option: `--owner <ACCOUNT_IDENTIFIER>`
+### Account Identifier ###
 
-Attributes accepted as <ACCOUNT_IDENTIFIER> (in order of search):
+Attributes accepted as `<ACCOUNT_IDENTIFIER>` (in order of search):
 
-- `"me"` (a predefined word, means the current logged-in account)
+- `"me"` (a predefined word which means the current logged-in account)
 - Account ID (always unique)
 - Email (always unique)
 - Username (always unique)
 
 ### Product Identifier ###
 
-Option: `--product <PRODUCT_IDENTIFIER>`
-
 Attributes accepted as `<PRODUCT_IDENTIFIER>` (in order of search):
 
 - Product ID (always unique)
 - Product name (unique among all Products owned by a particular user)
 
-### Device Group Identifier ###
+Hierarchical identifier pattern: `{<ACCOUNT_IDENTIFIER>}{<PRODUCT_IDENTIFIER>}`
 
-Option: `--dg <DEVICE_GROUP_IDENTIFIER>`
+Where `<ACCOUNT_IDENTIFIER>` is an [Account identifier](#account-identifier) attribute and `<PRODUCT_IDENTIFIER>` is a [Product identifier](#product-identifier) attribute. An attribute of the hierarchical identifier must not itself be a hierarchical identifier. An attribute of the hierarchical identifier must not contain the `}{` substring.
+
+### Device Group Identifier ###
 
 Attributes accepted as `<DEVICE_GROUP_IDENTIFIER>` (in order of search):
 
 - Device Group ID (always unique)
 - Device Group name (unique among all the Device Groups within a Product)
 
-### Device Identifier ###
+Hierarchical identifier pattern: `{<ACCOUNT_IDENTIFIER>}{<PRODUCT_IDENTIFIER>}{<DEVICE_GROUP_IDENTIFIER}`
+
+Where `<ACCOUNT_IDENTIFIER>` is an [Account identifier](#account-identifier) attribute, `<PRODUCT_IDENTIFIER>` is a [Product identifier](#product-identifier) attribute and `<DEVICE_GROUP_IDENTIFIER>` is a [Device Group identifier](#device-group-identifier) attribute. An attribute of the hierarchical identifier must not itself be a hierarchical identifier. An attribute of the hierarchical identifier must not contain the `}{` substring.
 
-Option: `--device <DEVICE_IDENTIFIER>`
+### Device Identifier ###
 
 Attributes accepted as `<DEVICE_IDENTIFIER>` (in order of search):
 
@@ -180,8 +192,6 @@ Attributes accepted as `<DEVICE_IDENTIFIER>` (in order of search):
 
 ### Build Identifier ###
 
-Option: `--build <BUILD_IDENTIFIER>`
-
 Attributes accepted as `<BUILD_IDENTIFIER>` (in order of search):
 
 - Deployment ID (always unique)
@@ -268,6 +278,35 @@ A test configuration file contains settings to run unit tests which are created
 
 ## Command Description ##
 
+### Account Information Commands ###
+
+#### Account Info ####
+
+```
+impt account info [--user <ACCOUNT_IDENTIFIER>] [--output <mode>] [--help]
+```
+
+Displays information about the specified account.
+
+| Option | Alias | Mandatory? | Value Required? | Description |
+| --- | --- | --- | --- | --- |
+| --user | -u | No | Yes | An [Account identifier](#account-identifier). If no account is specified, the current account is used |
+| --output | -z | No | Yes | Adjusts the [command's output](#command-output) |
+| --help | -h | No | No | Displays a description of the command. Ignores any other options |
+
+#### Account List ####
+
+```
+impt account list [--output <mode>] [--help]
+```
+
+Displays information about the current account and any other accounts on which the current account is collaborating.
+
+| Option | Alias | Mandatory? | Value Required? | Description |
+| --- | --- | --- | --- | --- |
+| --output | -z | No | Yes | Adjusts the [command's output](#command-output) |
+| --help | -h | No | No | Displays a description of the command. Ignores any other options |
+
 ### Authentication Commands ###
 
 #### Auth Info ####
@@ -893,7 +932,7 @@ The command allows you to add multiple devices to the newly created log stream.
 | Option | Alias | Mandatory? | Value Required? | Description |
 | --- | --- | --- | --- | --- |
 | --device | -d | No | Yes | The [device identifier](#device-identifier) of the device to be added to the log stream. This option may be repeated multiple times to specify multiple devices |
-| --dg | -g | no/[Project](#project-files) | Yes | A [Device Group identifier](#device-group-identifier). This option may be repeated multiple times to specify multiple Device Groups. Logs from all of the devices assigned to the specified Device Groups will be added to the log stream. `--device` and `--dg` options are cumulative. If neither the `--device` nor the `--dg` options are specified but there is a [Project file](#project-files) in the current directory, all of the devices assigned to the Device Group referenced by the [Project file](#project-files) are added |
+| --dg | -g | No/[Project](#project-files) | Yes | A [Device Group identifier](#device-group-identifier). This option may be included multiple times to specify multiple Device Groups. Logs from all of the devices assigned to the specified Device Groups will be added to the log stream. `--device` and `--dg` options are cumulative. If neither the `--device` nor the `--dg` options are specified but there is a [Project file](#project-files) in the current directory, all of the devices assigned to the Device Group referenced by the [Project file](#project-files) are added |
 | --output | -z | No | Yes | Adjusts the [command's output](#command-output) |
 | --help | -h | No | No | Displays a description of the command. Ignores any other options |
 
@@ -981,7 +1020,8 @@ Updates the specified login key’s description.
 #### Product Create ####
 
 ```
-impt product create --name <product_name> [--descr <product_description>] [--output <mode>] [--help]
+impt product create --name <product_name> [--descr <product_description>] [--owner <ACCOUNT_IDENTIFIER>]
+    [--output <mode>] [--help]
 ```
 
 Creates a new Product. Fails if a Product with the specified name already exists.
@@ -990,6 +1030,7 @@ Creates a new Product. Fails if a Product with the specified name already exists
 | --- | --- | --- | --- | --- |
 | --name | -n | Yes | Yes | The Product’s name. Must be unique among all of the current account’s Products |
 | --descr | -s | No | Yes | An optional description of the Product |
+| --owner | -o | No | Yes | The Product will be created in the [specified Account](#account-identifier). If no account is specified, the current account is used  |
 | --output | -z | No | Yes | Adjusts the [command's output](#command-output) |
 | --help | -h | No | No | Displays a description of the command. Ignores any other options |
 
@@ -1468,7 +1509,7 @@ Updates the specified webhook with a new target URL and/or MIME content-type. Fa
 | -s | --descr, --sha, --page-size, --stop-on-fail |
 | -t | --tag, --timeout, --temp, --target, --to, --tests |
 | -u | --user, --full, --unflagged, --unflag, --unassigned, --unbond, --url |
-| -v | |
+| -v | --version |
 | -w | --wh, --pwd |
 | -x | --device-file |
 | -y | --agent-file, --dg-type |