CommandsManual.md

impt Commands Manual

List Of Commands

impt account info
impt account list

impt auth info
impt auth login
impt auth logout

impt build cleanup
impt build copy
impt build delete
impt build deploy
impt build get
impt build info
impt build list
impt build run
impt build update

impt device assign
impt device info
impt device list
impt device remove
impt device restart
impt device unassign
impt device update

impt dg builds
impt dg create
impt dg delete
impt dg info
impt dg list
impt dg reassign
impt dg restart
impt dg unassign
impt dg update

impt log get
impt log stream

impt loginkey create
impt loginkey delete
impt loginkey info
impt loginkey list
impt loginkey update

impt product create
impt product delete
impt product info
impt product list
impt product update

impt project create
impt project delete
impt project info
impt project link
impt project update

impt test create
impt test delete
impt test github
impt test info
impt test run
impt test update

impt webhook create
impt webhook delete
impt webhook info
impt webhook list
impt webhook update

Contents

• Command Syntax
• The Help Option
• The Version Option
• Command Output
• Entity Identification
• Device Group Type
• Auth files
• Auth Environment Variables
• Command Execution Context
• Project Files
• Test Configuration Files
• Command Description
• List of Aliases
• Common Filter Options

Command Syntax

impt <command_group> <command_name> [<options>]

where:

• <command_group> is a logical group of commands.
• <command_name> is a command name, unique to the group.
• <options> are one or more options applicable to the command; most commands have options. Options may be written in any order.

Each option has the following format:

--<option_name> [<option_value>] or -<option_alias> [<option_value>]

where:

• <option_name> is unique across a particular command. For user convenience, many of the option names are reused across different commands.
• <option_alias> is a one-letter alias for the option. Unique across all option aliases for a particular command. The same option name in different commands always has the same alias.
• <option_value> is a value for the option. Not all options require values. If an option value has spaces or is empty, it must be placed in double quotes ("").

All commands and options are case sensitive.

The Help Option

The --help option (alias: -h) can be used with a fully or a partially specified command:

• impt --help — Displays a list of all the command groups.
• impt <command_group> --help — Displays a list of all of the group’s commands.
• impt <command_group> <command_name> --help — Displays a detailed description of the command.

The Version Option

• impt --version or impt -v — 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.

The --output option has the following <mode> values:

Value	Description
minimal	Only minimal output, mandated by the command, is generated; no additional colors are used in the output
json	The same as minimal, but all information (except user interaction) is displayed in the JSON format
debug	Debug information is added to the default output

Entity Identification

impt obeys the following rules when searching for any of the impCentral API entities — Account, Product, Device Group, Device and Deployment — described in this section:

• 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 for the specified value of this attribute.
• If no entity is found for this attribute, impt 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 under any 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).

Entity Identifiers must not be empty. An attribute of the hierarchical identifier must not itself be a hierarchical identifier or contain the }{ substring.

Account Identifier

Attributes accepted as <ACCOUNT_IDENTIFIER> (in order of search):

• "me" (a predefined word which means the current logged-in account)
• Account ID (always unique)
• Email (always unique)
• Username (always unique)

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)

Hierarchical identifier pattern: {<ACCOUNT_IDENTIFIER>}{<PRODUCT_IDENTIFIER>}

where <ACCOUNT_IDENTIFIER> is an Account identifier attribute and <PRODUCT_IDENTIFIER> is a Product identifier attribute.

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)

Hierarchical identifier pattern: {<ACCOUNT_IDENTIFIER>}{<PRODUCT_IDENTIFIER>}{<DEVICE_GROUP_IDENTIFIER}

where <ACCOUNT_IDENTIFIER> is an Account identifier attribute, <PRODUCT_IDENTIFIER> is a Product identifier attribute and <DEVICE_GROUP_IDENTIFIER> is a Device Group identifier attribute.

Device Identifier

Attributes accepted as <DEVICE_IDENTIFIER> (in order of search):

• Device ID (always unique)
• MAC address
• Agent ID
• Device name

Build Identifier

Attributes accepted as <BUILD_IDENTIFIER> (in order of search):

• Deployment ID (always unique)
• SHA
• Tag
• Origin

Device Group Type

impt commands accept the following constants to specify a type of Device Group:

• development — for the impCentral API’s "development_devicegroup" type
• pre-factory — for the impCentral API’s "pre_factoryfixture_devicegroup" type
• pre-dut — for the impCentral API’s "pre_dut_devicegroup" type
• pre-production — for the impCentral API’s "pre_production_devicegroup" type
• factory — for the impCentral API’s "factoryfixture_devicegroup" type
• dut — for the impCentral API’s "dut_devicegroup" type
• production — for the impCentral API’s "production_devicegroup" type

Auth Files

An auth file is a .impt.auth file. It stores authentication and other information necessary to execute impt commands.

Local Auth File

A local auth file is an auth file located in the directory from where an impt command is called. Different directories may contain different local auth files. One directory can contain only one local auth file.

Global Auth File

There can be none or only one global auth file per impt installation.

Auth Environment Variables

impt recognizes the following environment variables:

• IMPT_AUTH_FILE_PATH — a path to a directory with an auth file.
• IMPT_LOGINKEY — a login key for the account.
• IMPT_USER — an account identifier: a username or an email address.
• IMPT_PASSWORD — an account password.
• IMPT_ENDPOINT — an impCentral API endpoint (the API base URL).

Command Execution Context

This is how impt determines a context (authentication and other settings) for execution of a command.

1. If the current directory contains an auth file (local auth file):

   • The command is executed in the context defined by this file.
   • If the file is broken, the command fails.

2. Otherwise, if the IMPT_AUTH_FILE_PATH environment variable is set:

   • The command is executed in the context defined by the auth file in the directory referenced by this environment variable.
   • If the file does not exist or is broken, the command fails.

3. Otherwise, if the IMPT_LOGINKEY environment variable is set:

   • impt tries to login using the specified login key and then the command is executed in the context of this login.
   • If multi-factor authentication is enabled for the account, the user is asked to enter a one-time password.
   • If the login fails, the command fails.
   • If the IMPT_ENDPOINT environment variable is set, its value is used as the impCentral API endpoint. Otherwise the default endpoint (https://api.electricimp.com/v5) is used.

4. Otherwise, if the IMPT_USER environment variable is set:

   • impt tries to login using the specified account identifier (user) and a password and then the command is executed in the context of this login.
   • If the IMPT_PASSWORD environment variable is set, its value is used as a password. Otherwise the user is asked to input the password.
   • If multi-factor authentication is enabled for the account, the user is asked to enter a one-time password.
   • If the login fails, the command fails.
   • If the IMPT_ENDPOINT environment variable is set, its value is used as the impCentral API endpoint. Otherwise the default endpoint (https://api.electricimp.com/v5) is used.

5. Otherwise, if the global auth file exists:

   • The command is executed in the context defined by this file.
   • If the file is broken, the command fails.

6. Otherwise, the command fails (as no authentication information has been found to execute the command).

Project Files

A Project file is a .impt.project file located in a given directory. Different directories may contain different Project files. A directory can contain only one Project file.

Each Project file contains settings for a Project, an impt entity which links the source files in the current directory with a Device Group. A Project file references the linked Device Group (of the types development or pre-factory only) and, correspondingly, the Product which contains that Device Group, devices assigned to the Device Group, and Deployments created for that Device Group.

A Project file may affect commands called from the directory where the file is located. Product, Device Group, Devices, Deployment, and source code files referenced by Project file may be assumed by a command when they are not specified explicitly.

Test Configuration Files

A test configuration file is a .impt.test file located in a given directory. Different directories may contain different test configuration files. A directory can contain only one test configuration file.

A test configuration file contains settings to run unit tests which are created with the impUnit test framework. Test configuration files affect Test Commands only.

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. If no account is specified, the current account is used
--output	-z	No	Yes	Adjusts the command’s 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
--help	-h	No	No	Displays a description of the command. Ignores any other options

Authentication Commands

Auth Info

impt auth info [--output <mode>] [--help]

Displays the status and the details of the authentication applicable to the current directory.

Applicable authentication settings are determined according to the Command Execution Context rules.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Auth Login

impt auth login [--local] [--endpoint <endpoint_url>]
    [--user <user_id> [--pwd <password>] | --lk <login_key_id>] [--temp] [--confirmed]
    [--output <mode>] [--help]

Creates the global or local auth file.

The options for one, and only one, of the following authentication methods may be specified in the command:

• Using an account identifier and password (--user and --pwd options).
• Using a login key (--lk option).

If neither the --user nor the --lk option is specified, the user is asked to choose an authentication method and input the corresponding credentials.

If the --user option is specified but the --pwd option is not, the user is asked to input the account password.

If multi-factor authentication is enabled for the account, the user is asked to input one-time password.

The user is asked to confirm the operation if the corresponding auth file already exists, unless confirmed automatically with the --confirmed option. If confirmed, the existing auth file is overwritten.

Option	Alias	Mandatory?	Value Required?	Description
--local	-l	No	No	If specified, creates or replaces a local auth file in the current directory. If not specified, creates or replaces the global auth file
--endpoint	-e	No	Yes	The base impCentral API URL. Default: https://api.electricimp.com/v5
--user	-u	No	Yes	The account identifier: a username or an email address
--pwd	-w	No	Yes	The account password. If specified, the --user option must be specified too
--lk	-k	No	Yes	A login key for the account
--temp	-t	No	No	If this option is not specified, impt saves the information required to refresh access token and refreshes it automatically when the token expires. If the option is specified, the tool does not save information required to refresh access token. In this case, you need to call impt auth login again after the access token has expired
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Auth Logout

impt auth logout [--local] [--output <mode>] [--help]

Deletes the global or local auth file.

Option	Alias	Mandatory?	Value Required?	Description
--local	-l	No	No	If specified, deletes the local auth file if one exists in the current directory. If not specified, it deletes the global auth file if it exists
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Manipulation Commands

Build Cleanup

impt build cleanup [--product <PRODUCT_IDENTIFIER>] [--unflag] [--confirmed] [--output <mode>] [--help]

Deletes builds (Deployments) which are not related to any Device Group (‘zombie’ builds).

If the --product option is specified, the command deletes Deployments which are not related to any Device Group but are related to the specified Product. That Product is not deleted. If the --product option is not specified, the command deletes all Deployments owned by the current account and which are not related to any Device Group. This includes Deployments which relate to Products that exist as well as Products that were deleted.

If a Deployment has its flagged attribute set to true and the --unflag option is not specified, this Deployment is excluded from the deletion. If the --unflag option is specified, such a Deployment is deleted.

The user is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--product	-p	No	Yes	A Product identifier
--unflag	-u	No	No	Delete a Deployment even if it has its flagged attribute set to true
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Copy

impt build copy [--build <BUILD_IDENTIFIER>] --dg <DEVICE_GROUP_IDENTIFIER> [--all]
    [--output <mode>] [--help]

Copies the specified build (Deployment) to a new Deployment related to the specified Device Group. Fails if the specified Deployment or the specified Device Group does not exist.

The new build for the specified Device Group is created from the device and agent source code that the specified original build has. If the --all option is specified, all other attributes (description, origin, flagged status and tags) are copied to the new build as well.

The new build is not run until the devices are rebooted. To run it, use impt dg restart or impt device restart.

Build source code is not saved locally. To download the source code from a Deployment, call impt build get.

Option	Alias	Mandatory?	Value Required?	Description
--build	-b	Yes/Project	Yes	The Build identifier of the Deployment to be copied. If not specified, the most recent Deployment for the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--dg	-g	Yes	Yes	The Device Group identifier of the Device Group the new Deployment is created for
--all	-a	No	No	Copy all attributes of the specified Deployment
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Delete

impt build delete --build <BUILD_IDENTIFIER> [--force] [--confirmed] [--output <mode>] [--help]

Deletes the specified build (Deployment). The command fails if the build is the Device Group’s min_supported_deployment (see the impCentral API specification) or a newer Deployment. The command also fails if the Deployment has its flagged attribute set to true and the --force option was not specified. Use either the --force option or impt build update to update the attribute.

The user is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--build	-b	Yes	Yes	A Build identifier
--force	-f	No	No	If the Deployment has its flagged attribute set to true, set it to false to allow deletion
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Deploy

impt build deploy [--dg <DEVICE_GROUP_IDENTIFIER>] [--device-file <device_file>]
    [--agent-file <agent_file>] [--descr <build_description>] [--origin <origin>]
    [--tag <tag>] [--flagged [true|false]] [--output <mode>] [--help]

Creates a build (Deployment) from the specified source files, with a description (if specified) and attributes (if specified), and deploys it to all the devices assigned to the specified Device Group.

The command fails if one or both of the specified source files do not exist, or the specified Device Group does not exist.

The new build is not run until the devices are rebooted. To run it, call impt dg restart or impt device restart.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--device-file	-x	No	Yes	The device source code file name. If not specified, the file referenced by the Project file in the current directory is used; if there is no Project file, empty code is used. If the specified file does not exist, the command fails
--agent-file	-y	No	Yes	The agent source code file name. If not specified, the file referenced by the Project file in the current directory is used; if there is no Project file, empty code is used. If the specified file does not exist, the command fails
--descr	-s	No	Yes	A description of the build (Deployment)
--origin	-o	No	Yes	A free-form key to store a link to the code’s storage location, eg. a GitHub repo name or URL
--tag	-t	No	Yes	A tag applied to this build (Deployment). This option may be repeated multiple times to apply multiple tags
--flagged	-f	No	No	If true or no value, this build (Deployment) cannot be deleted without first setting this option back to false. If false or the option is not specified, the build can be deleted
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Get

impt build get [--build <BUILD_IDENTIFIER>] [--device-file <device_file>]
    [--agent-file <agent_file>] [--device-only] [--agent-only]
    [--confirmed] [--output <mode>] [--help]

Downloads the source files of the specified build (Deployment) and displays information about the build.

The user is asked to confirm the operation if the files with the specified names already exist in the current directory, unless confirmed automatically with the --confirmed option. If confirmed, the existing files are overwritten.

Option	Alias	Mandatory?	Value Required?	Description
--build	-b	Yes/Project	Yes	A Build identifier. If not specified, the most recent Deployment for the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--device-file	-x	No	Yes	The device source code file name. If not specified, the file referenced by the Project file in the current directory is used; if there is no Project file and the --agent-only option is not specified, the command fails
--agent-file	-y	No	Yes	The agent source code file name. If not specified, the file referenced by the Project file in the current directory is used; if there is no Project file and the --device-only option is not specified, the command fails
--device-only	-i	No	No	Downloads the source code for the device only
--agent-only	-j	No	No	Downloads the source code for the agent only
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Info

impt build info [--build <BUILD_IDENTIFIER>] [--output <mode>] [--help]

Displays information about the specified build (Deployment).

Option	Alias	Mandatory?	Value Required?	Description
--build	-b	Yes/Project	Yes	A Build identifier. If not specified, the most recent Deployment for the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build List

impt build list [--owner <ACCOUNT_IDENTIFIER>] [--product <PRODUCT_IDENTIFIER>]
    [--dg <DEVICE_GROUP_IDENTIFIER>] [--dg-type <device_group_type>]
    [--sha <deployment_sha>] [--tag <tag>] [--flagged] [--unflagged]
    [--non-zombie] [--zombie] [--output <mode>] [--help]

Displays information about all of the builds (Deployments) available to the current account.

The returned list of the builds may be filtered. Filtering uses any combination of the described filter options. Filter options may be repeated. All filter options with the same name are combined by logical OR, then all filter options with different names are combined by logical AND.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Filter Option	Alias	Mandatory?	Value Required?	Description
--owner	-o	No	Yes	Builds owned by the specified Account(s) only
--product	-p	No	Yes	Builds deployed to Device Groups which belong to the specified Product(s) only
--dg	-g	No	Yes	Builds deployed to the specified Device Group(s) only
--dg-type	-y	No	Yes	Builds deployed to Device Groups of the specified type only
--sha	-s	No	Yes	Builds with the specified SHA only
--tag	-t	No	Yes	Builds with the specified tag only
--flagged	-f	No	No	Builds with the flagged attribute set to true only
--unflagged	-u	No	No	Builds with the flagged attribute set to false only
--non-zombie	-n	No	No	Only builds which are related to a Device Group
--zombie	-m	No	No	Only builds which are not related to any Device Group

Build Run

impt build run [--dg <DEVICE_GROUP_IDENTIFIER>] [--device-file <device_file>]
    [--agent-file <agent_file>] [--descr <build_description>]
    [--origin <origin>] [--tag <tag>] [--flagged [true|false]]
    [--conditional] [--log] [--output <mode>] [--help]

Creates, deploys and runs a build (Deployment). Optionally, displays logs of the running build.

It behaves exactly like impt build deploy followed by impt dg restart and, optionally, by impt log stream.

The command fails if one or both of the specified source files do not exist, or the specified Device Group does not exist. Informs the user if the specified Device Group does not have assigned devices; in this case, the Deployment is created anyway.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--device-file	-x	No	Yes	The device source code file name. If not specified, the file referenced by the Project file in the current directory is used; if there is no Project file, empty code is used. If the specified file does not exist, the command fails
--agent-file	-y	No	Yes	The agent source code file name. If not specified, the file referenced by the Project file in the current directory is used; if there is no Project file, empty code is used. If the specified file does not exist, the command fails
--descr	-s	No	Yes	A description of the build (Deployment)
--origin	-o	No	Yes	A free-form key to store the source location of the code
--tag	-t	No	Yes	A tag applied to this build (Deployment). This option may be repeated multiple times to apply multiple tags
--flagged	-f	No	No	If true or no value is supplied, this build (Deployment) cannot be deleted without first setting this option back to false. If false or the option is not specified, the build can be deleted
--conditional	-c	No	No	Trigger a conditional restart of the devices assigned to the specified Device Group instead of a normal restart (see the impCentral API specification)
--log	-l	No	No	Starts displaying logs from the devices assigned to the specified Device Group (see the impt log stream description). To stop displaying the logs, press Ctrl-C
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Build Update

impt build update [--build <BUILD_IDENTIFIER>] [--descr <build_description>]
    [--tag <tag>] [--remove-tag <tag>] [--flagged [true|false]]
    [--output <mode>] [--help]

Updates the description, tags and/or the flagged attribute (whichever is specified) of the specified build (Deployment). Fails if the specified build (Deployment) does not exist.

Option	Alias	Mandatory?	Value Required?	Description
--build	-b	Yes/Project	Yes	A Build identifier. If not specified, the most recent Deployment for the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--descr	-s	No	Yes	A description of the build (Deployment)
--tag	-t	No	Yes	A tag applied to this build (Deployment). This option may be repeated multiple times to apply multiple tags
--remove-tag	-r	No	Yes	A tag removed from this build (Deployment). This option may be repeated multiple times to remove multiple tags
--flagged	-f	No	No	If true or no value is supplied, this build (Deployment) cannot be deleted without first setting this option back to false. If false or the option is not specified, the build can be deleted
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Manipulation Commands

Device Assign

impt device assign --device <DEVICE_IDENTIFIER> [--dg <DEVICE_GROUP_IDENTIFIER>]
    [--confirmed] [--output <mode>] [--help]

Assigns the specified device to the specified Device Group. Fails if the specified Device Group does not exist.

The user is asked to confirm the operation if the specified Device is already assigned to another Device Group. If the operation is confirmed (manually or automatically with the --confirmed option), the device is reassigned to the new Device Group.

The operation may fail for some combinations of Device Group types, for some kinds of device, or operations such as reassigning across Products.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes	Yes	A device identifier
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project Files in the current directory is used (if there is no Project file, the command fails)
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Info

impt device info --device <DEVICE_IDENTIFIER> [--output <mode>] [--help]

Displays information about the specified device.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes	Yes	A device identifier
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device List

impt device list [--owner <ACCOUNT_IDENTIFIER>] [--product <PRODUCT_IDENTIFIER>]
    [--dg <DEVICE_GROUP_IDENTIFIER>] [--dg-type <device_group_type>] [--unassigned]
    [--assigned] [--online] [--offline] [--output <mode>] [--help]

Displays information about all of the devices available to the current account.

The returned list of the devices may be filtered. Filtering uses any combination of the described filter options. Filter options may be repeated. All filter options with the same name are combined by logical OR, then all filter options with different names are combined by logical AND.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Filter Option	Alias	Mandatory?	Value Required?	Description
--owner	-o	No	Yes	Devices owned by the specified Account(s) only
--product	-p	No	Yes	Devices assigned to Device Groups which belong to the specified Product(s) only
--dg	-g	No	Yes	Devices assigned to the specified Device Group(s) only
--dg-type	-y	No	Yes	Devices assigned to Device Groups of the specified type only
--unassigned	-u	No	No	Unassigned devices only
--assigned	-a	No	No	Assigned devices only
--online	-n	No	No	Devices in online state only
--offline	-f	No	No	Devices in offline state only

Device Remove

impt device remove --device <DEVICE_IDENTIFIER> [--force] [--confirmed] [--output <mode>] [--help]

Removes the specified Device from the current account.

The command fails if the device is assigned to a Device Group and the --force option is not specified. Use either --force or impt device unassign to unassign the device before removal.

The user is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes	Yes	A device identifier
--force	-f	No	No	If the device is assigned to a Device Group, unassign it first
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Restart

impt device restart --device <DEVICE_IDENTIFIER> [--conditional] [--log] [--output <mode>] [--help]

Reboots the specified device and, optionally, starts displaying logs from it.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes	Yes	A device identifier
--conditional	-c	No	No	Trigger a conditional restart (see the impCentral API specification)
--log	-l	No	No	Start displaying logs from the specified device (see impt log stream). To stop displaying the logs press Ctrl-C
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Unassign

impt device unassign --device <DEVICE_IDENTIFIER> [--unbond <unbond_key>] [--output <mode>] [--help]

Unassigns the specified device. Does nothing if the device already unassigned.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes	Yes	A device identifier
--unbond	-u	No	Yes	An unbond key is required to unassign the specified device from a Device Group of the production type
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Update

impt device update --device <DEVICE_IDENTIFIER> --name <device_name> [--output <mode>] [--help]

Updates the name of the specified device.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes	Yes	A device identifier
--name	-n	Yes	Yes	The device’s new name
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Manipulation Commands

Device Group Builds

impt dg builds [--dg <DEVICE_GROUP_IDENTIFIER>] [--unflag] [--unflag-old] [--remove]
    [--confirmed] [--output <mode>] [--help]

Updates and/or deletes builds (Deployments) belonging to the specified Device Group and displays information about all of the Device Group’s Deployments at the end of the command execution (as with impt build list).

The user is asked to confirm the operation if any Deployment is going to be deleted, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project File in the current directory is used (if there is no Project file, the command fails)
--unflag	-u	No	No	Set the flagged attribute to false for all the Deployments of the specified Device Group
--unflag-old	-o	No	No	Set the flagged attribute to false for all the Deployments of the specified Device Group which are older than min_supported_deployment (see the impCentral API specification)
--remove	-r	No	No	Deletes all of the specified Device Group’s Deployments which are older than min_supported_deployment (see the impCentral API specification) and have their flagged attribute set to false. This option works after the --unflag/--unflag-old options
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Create

impt dg create --name <device_group_name> [--dg-type <device_group_type>]
    [--product <PRODUCT_IDENTIFIER>] [--descr <device_group_description>]
    [--dut <DEVICE_GROUP_IDENTIFIER>] [--target <DEVICE_GROUP_IDENTIFIER>]
    [--env-variable <user-env-variable>] 
    [--region <region_name>] [--output <mode>] [--help]

Creates a new Device Group for the specified Product. Fails if a Device Group with the specified name already exists under the specified Product.

Option	Alias	Mandatory?	Value Required?	Description
--name	-n	Yes	Yes	The new Device Group’s name. Must be unique among all Device Groups belonging to the specified Product
--dg-type	-y	No	Yes	The new Device Group’s type. Default: development. If the type value is invalid, the command fails
--product	-p	Yes/Project	Yes	The Product identifier of the Product to which the Device Group belongs. If not specified, the Product referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--descr	-s	No	Yes	An optional description of the Device Group
--dut	-u	No	Yes	The Device Group identifier of the new Device Group’s target device-under-test Device Group. Should only be specified for factory or pre-factory Device Groups. The target Device Group must be of the corresponding type dut or pre-dut, and belong to the same Product as the specified Device Group. Otherwise the command fails
--target	-t	No	Yes	The Device Group identifier of the new Device Group’s target production Device Group. Should only be specified for factory or pre-factory Device Groups. The target Device Group must be of the corresponding type production or pre-production, and belong to the same Product as the specified Device Group. Otherwise the command fails
--env-variable	-e	No	Yes	Custom variables that can be used in the Device Group's code. Only Owners have permissions to edit. Must be valid JSON and enclosed in single quotes. Keys must be alphanumeric, and start with a letter. Values must be strings or numbers. A new deployment will need to be created, and devices restarted
--region	-r	No	Yes	A region. May be specified if the new Device Group is of the production or pre-production type only
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Delete

impt dg delete [--dg <DEVICE_GROUP_IDENTIFIER>] [--force] [--confirmed] [--output <mode>] [--help]

Deletes the specified Device Group and all of the related builds (Deployments).

The command fails if the Device Group is a device-under-test target or production target of another Device Group. Use either impt dg update to update the the other Device Group’s target/dut, or impt dg delete to delete the other Device Group before the specified one.

The command also fails when the --force option is not specified and:

• There are devices assigned to the specified Device Group. Use either the --force option, impt dg unassign or impt dg reassign to unassign the devices from this Device Group.
• The Device Group has any Deployments with their flagged attribute set to true. Use either the --force option or impt build update to update this attribute.

The user is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--force	-f	No	No	Unassigns all of the Device Group’s devices as with impt dg unassign, and set the flagged attribute to false for all of the Device Group’s Deployments
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Info

impt dg info [--dg <DEVICE_GROUP_IDENTIFIER>] [--full] [--output <mode>] [--help]

Displays information about the specified Device Group.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--full	-u	No	No	Displays additional information, including details about the devices assigned to the Device Group, and Webhooks created for the Device Group
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group List

impt dg list [--owner <ACCOUNT_IDENTIFIER>] [--product <PRODUCT_IDENTIFIER>]
    [--dg-type <device_group_type>] [--output <mode>] [--help]

Displays information about all Device Groups available to the current account.

The returned list of the Device Groups may be filtered. Filtering uses any combination of the described filter options. Filter options may be repeated. All filter options with the same name are combined by logical OR, then all filter options with different names are combined by logical AND.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Filter Option	Alias	Mandatory?	Value Required?	Description
--owner	-o	No	Yes	Device Groups owned by the specified Account(s) only
--product	-p	No	Yes	Device Groups which belong to the specified Product(s) only
--dg-type	-y	No	Yes	Device Groups of the specified type only

Device Group Reassign

impt dg reassign --from <DEVICE_GROUP_IDENTIFIER> [--to <DEVICE_GROUP_IDENTIFIER>]
    [--output <mode>] [--help]

Reassigns all of the devices from one Device Group to another. Fails if any of the specified Device Groups does not exist.

The operation may also fail for some combinations of Device Group type, for some types of device, and for certain attempts to reassign devices across Products.

Option	Alias	Mandatory?	Value Required?	Description
--from	-f	Yes	Yes	The Device Group identifier of the origin Device Group
--to	-t	Yes/Project	Yes	The Device Group identifier of the destination Device Group. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Restart

impt dg restart [--dg <DEVICE_GROUP_IDENTIFIER>] [--conditional] [--log] [--output <mode>] [--help]

Reboots all of the devices assigned to the specified Device Group and, optionally, starts displaying logs from them. Does nothing if the Device Group has no devices assigned to it.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--conditional	-c	No	No	Trigger a conditional restart (see the impCentral API specification)
--log	-l	No	No	Start displaying logs from the devices assigned to the specified Device Group (see impt log stream). To stop displaying the logs press Ctrl-C
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Unassign

impt dg unassign [--dg <DEVICE_GROUP_IDENTIFIER>] [--unbond <unbond_key>] [--output <mode>] [--help]

Unassigns all of the devices from the specified Device Group. Does nothing if the Device Group has no devices assigned to it.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--unbond	-u	No	Yes	An unbond key is required to unassign devices from a Device Group of the type production
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Device Group Update

impt dg update [--dg <DEVICE_GROUP_IDENTIFIER>] [--name <device_group_name>]
    [--descr <device_group_description>]
    [--dut <DEVICE_GROUP_IDENTIFIER>] [--target <DEVICE_GROUP_IDENTIFIER>]
    [--load-code-after-blessing [true|false]]
    [--env-variable <user-env-variable>] 
    [--min-supported-deployment <BUILD_IDENTIFIER>] [--output <mode>] [--help]

Updates the specified Device Group. Fails if the specified Device Group does not exist.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--name	-n	No	Yes	The Device Group’s new name. Must be unique among all of the Device Groups belonging to the Product
--descr	-s	No	Yes	An optional description of the Device Group
--dut	-u	No	Yes	The Device Group identifier of the new Device Group’s target device-under-test Device Group. Should only be specified for factory or pre-factory Device Groups. The target Device Group must be of the corresponding type dut or pre-dut, and belong to the same Product as the specified Device Group. Otherwise the command fails
--target	-t	No	Yes	The Device Group identifier of the new Device Group’s target production Device Group. Should only be specified for factory or pre-factory Device Groups. The target Device Group must be of the corresponding type production or pre-production, and belong to the same Product as the specified Device Group. Otherwise the command fails
--load-code-after-blessing	-l	No	No	Only applicable to production and pre-production Device Groups. If true or no value is supplied, production application code is immediately loaded by the device after blessing. If false, production code will be loaded when the device first connects as part of BlinkUp. Newly created Production Device Groups default this setting to true
--min-supported-deployment	-m	No	Yes	The Build identifier of the new min_supported_deployment (see the impCentral API specification). The Deployment should belong to this Device Group and should be newer than the current min_supported_deployment
--env-variable	-e	No	Yes	Custom variables that can be used in the Device Group's code. Only Owners have permissions to edit. Must be valid JSON and enclosed in single quotes. Keys must be alphanumeric, and start with a letter. Values must be strings or numbers. A new deployment will need to be created, and devices restarted
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Log Manipulation Commands

Log Get

impt log get [--device <DEVICE_IDENTIFIER>] [--page-size <number_of_entries>]
    [--page-number <page_number>] [--output <mode>] [--help]

Displays historical logs for the specified device. The logs are displayed with the most recent entry first.

Note The impCloud retains only a limited number of log entries, for a limited period of time.

If the --page-number option is specified, the command displays the specified page of the log entries and completes. If the --page-number option is not specified, the command displays all saved log entries by pages, starting from the page with the most recent log entries. After every page of log entries is displayed, the command is paused:

• To display the next page press Enter
• To abort the command press Ctrl-C

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	Yes/Project	Yes	A device identifier. If not specified and there is only one device in the Device Group referenced by the Project file in the current directory, then this device is used (if there is no Project file, or the Device Group has none or more than one device, the command fails)
--page-size	-s	No	Yes	Number of log entries in one page. Default: 20
--page-number	-n	No	Yes	Ordinal page number with the log entries to display. Must have a positive value. Page 1 is a page with the most recent log entries. If not specified, the command displays all saved log entries
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Log Stream

impt log stream [--device <DEVICE_IDENTIFIER>] [--dg <DEVICE_GROUP_IDENTIFIER>] [--output <mode>] [--help]

Creates a log stream and displays logs from the specified devices in real-time. To stop displaying the logs press Ctrl-C.

Important No other command can be called while the logs are being streamed.

The impCentral API permits an account to have only a limited number of log streams at a time. If the limit is reached and a new log stream is created, an existing one is automatically closed.

The command allows you to add multiple devices to the newly created log stream. It is also possible to specify one or more Device Groups. Logs from all devices assigned to the specified Device Groups as well as from directly specified Devices will be displayed in the newly created log stream. However, the impCentral API has a limit to the number of devices allowed in one log stream. The tool does not check this limit and allow you to specify any number of devices. Check the operation output to see which devices were actually added to the log stream.

Option	Alias	Mandatory?	Value Required?	Description
--device	-d	No	Yes	The 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	Yes	A 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 in the current directory, all of the devices assigned to the Device Group referenced by the Project file are added
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Login Key Manipulation Commands

Login Key Create

impt loginkey create [--pwd <password>] [--descr <login_key_description>] [--output <mode>] [--help]

Creates a new login key for the current account.

Note There is a limit on the total number of login keys available per account. Use impt loginkey delete to delete an existing login key if this this limit is exceeded.

Option	Alias	Mandatory?	Value Required?	Description
--pwd	-w	No	Yes	The account password. If no password is specified, the user is asked to input one
--descr	-s	No	Yes	An optional description of the login key, eg. "John's key"
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Login Key Delete

impt loginkey delete --lk <login_key_id> [--pwd <password>] [--confirmed] [--output <mode>] [--help]

Deletes the specified login key. The user is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--lk	-k	Yes	Yes	The login key ID
--pwd	-w	No	Yes	The account password. If no password is specified, the user is asked to input one
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Login Key Info

impt loginkey info --lk <login_key_id> [--output <mode>] [--help]

Displays information about the specified Login Key.

Option	Alias	Mandatory?	Value Required?	Description
--lk	-k	Yes	Yes	The login key ID
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Login Key List

impt loginkey list [--output <mode>] [--help]

Displays information about all of the login keys belonging to the current account.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Login Key Update

impt loginkey update --lk <login_key_id> [--pwd <password>] --descr <login_key_description>
    [--output <mode>] [--help]

Updates the specified login key’s description.

Option	Alias	Mandatory?	Value Required?	Description
--lk	-k	Yes	Yes	The login key ID
--pwd	-w	No	Yes	The account password. If no password is specified, the user is asked to input one
--descr	-s	Yes	Yes	The login key’s new description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Product Manipulation Commands

Product Create

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.

Option	Alias	Mandatory?	Value Required?	Description
--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. If no account is specified, the current account is used
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Product Delete

impt product delete [--product <PRODUCT_IDENTIFIER>] [--builds] [--force] [--confirmed]
    [--output <mode>] [--help]

Deletes the specified Product.

The command fails if the Product has any Device Groups and the --force option was not specified. Use either the --force option, or impt dg delete to delete the Product’s Device Groups.

The user is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--product	-p	Yes/Project	Yes	A Product identifier. If not specified, the Product referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--builds	-b	No	No	Additionally deletes all Deployments related to all of the Device Groups which belong to the Product, including Device Groups that were deleted previously. The command fails if any Deployment has its flagged attribute set to true and the --force option was not specified
--force	-f	No	No	Deletes all of the Product’s Device Groups as with impt dg delete --force called for every one of the Product’s Device Groups
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Product Info

impt product info [--product <PRODUCT_IDENTIFIER>] [--full] [--output <mode>] [--help]

Displays information about the specified Product.

Option	Alias	Mandatory?	Value Required?	Description
--product	-p	Yes/Project	Yes	A Product identifier. If not specified, the Product referenced by the Project File in the current directory is used (if there is no Project file, the command fails)
--full	-u	No	No	Displays additional information and the full structure of the Product, including details about every Device Group that belongs to the Product, and devices assigned to those Device Groups
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Product List

impt product list [--owner <ACCOUNT_IDENTIFIER>] [--output <mode>] [--help]

Displays information about all of the Products available to the current account.

The returned list of the Products may be filtered. Filtering uses any combination of the described filter options. Every filter option may be repeated multiple times. All filter options with the same name are combined by logical OR, then all filter options with different names are combined by logical AND.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Filter Options	Alias	Mandatory?	Value Required?	Description
--owner	-o	No	Yes	Products owned by the specified Account(s) only

Product Update

impt product update [--product <PRODUCT_IDENTIFIER>] [--name <product_name>]
    [--descr <product_description>] [--output <mode>] [--help]

Updates the specified Product with a new name and/or description. Fails if the specified Product does not exist.

Option	Alias	Mandatory?	Value Required?	Description
--product	-p	Yes/Project	Yes	A Product identifier. If not specified, the Product referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--name	-n	No	Yes	The Product’s new name. Must be unique among all of the current Account’s Products
--descr	-s	No	Yes	The Product’s new description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Project Manipulation Commands

Project Create

impt project create --product <PRODUCT_IDENTIFIER> [--create-product] --name <device_group_name>
    [--descr <device_group_description>] [--device-file <device_file>] [--agent-file <agent_file>]
    [--pre-factory] [--dut <DEVICE_GROUP_IDENTIFIER>] [--create-dut]
    [--target <DEVICE_GROUP_IDENTIFIER>] [--create-target] [--confirmed]
    [--output <mode>] [--help]

Creates a new Device Group for the specified Product and creates a new Project file in the current directory by linking it to the new Device Group.

The command fails if:

• The specified Product does not exist and the --create-product option was not specified. Use either the --create-product option or the impt product create command to create the Product first.
• The Device Group with the specified name already exist in the specified Product. Use impt project link to create the Project linked to that Device Group.
• The optionally specified target device-under-test Device Group does not exist and the --create-dut option was not specified. Use either the --create-dut option or the impt dg create command to create the required Device Group of the type pre-dut.
• The optionally specified target production Device Group does not exist and the --create-target option was not specified. Use either the --create-target option or the impt dg create command to create the required Device Group of the type pre-production.

The user is asked to confirm the operation if the current directory already contains a Project file, unless confirmed automatically with the --confirmed option. If confirmed, the existing Project file is overwritten.

The new Device Group will be of the type development or pre-factory (set with the --pre-factory option).

At the end of the command execution, information about the Project is displayed (as by impt project info).

Option	Alias	Mandatory?	Value Required?	Description
--product	-p	Yes	Yes	A Product identifier
--create-product	-c	No	No	If the Product specified by the --product option does not exist, it is created. In this case, the value of --product is used as the name of the new Product. If the Product specified already exists, --create-product is ignored
--name	-n	Yes	Yes	The name of the new Device Group. Must be unique among all Device Groups in the specified Product
--descr	-s	No	Yes	The Device Group’s optional description
--device-file	-x	No	Yes	The device source code file name. Default: device.nut. If the file does not exist, an empty file is created
--agent-file	-y	No	Yes	The agent source code file name. Default: agent.nut. If the file does not exist, an empty file is created
--pre-factory	-f	No	No	If not specified, the new Device Group is of the type development. If specified, the new Device Group is of the type pre-factory
--dut	-u	No	Yes	The Device Group identifier of the new Project Device Group’s target device-under-test Device Group. May be specified only if --pre-factory is also specified. The specified Device Group must be of the type pre-dut and belong to the specified Product. Otherwise the command fails
--create-dut	-w	No	No	If the Device Group specified by the --dut option does not exist, it is created. In this case, the value of --dut is used as the name of the new Device Group. If --dut is not specified or the Device Group specified by --dut exists, --create-dut is ignored
--target	-t	No	Yes	The Device Group identifier of the new Project Device Group’s target production Device Group. May be specified only if --pre-factory is also specified. The specified Device Group must be of the type pre-production and belong to the specified Product. Otherwise the command fails
--create-target	-r	No	No	If the Device Group specified by the --target option does not exist, it is created. In this case, the value of --target is used as the name of the new Device Group. If --target is not specified or the Device Group specified by --target exists, --create-target is ignored
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Project Delete

impt project delete [--entities] [--files] [--all] [--confirmed] [--output <mode>] [--help]

Deletes the Project file in the current directory and, optionally, the impCentral API entities (Device Group, Product, Deployments) related to the Project, and, optionally, the local source files. Does nothing if there is no Project file in the current directory.

If the --entities option is specified, the command additionally:

• Unassigns all devices from the Project Device Group.
• Deletes the Project Device Group.
• Deletes all of the Project Device Group’s builds (Deployments), including Deployments with their flagged attribute set to true.
• If the Project Device Group has a device-under-test Device Group target which is only targeted by the Project Device Group:
  • Unassigns all devices from the target device-under-test Device Group.
  • Deletes the target device-under-test Device Group.
  • Deletes all of the target device-under-test Device Group’s builds (Deployments), including Deployments with their flagged attribute set to true.
• If the Project Device Group has a production Device Group target which is only targeted by the Project Device Group:
  • Unassigns all devices from the target production Device Group.
  • Deletes the target production Device Group.
  • Deletes all of the target production Device Group’s builds (Deployments), including Deployments with their flagged attribute set to true.
• If the Product which contains the Project Device Group includes only the Project Device Group and, if applicable, the Device Group target(s) mentioned above.

The user is informed about all entities and files which are going to be deleted or updated, and is asked to confirm the operation, unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--entities	-e	No	No	Also deletes all of the impCentral API entities (Device Group, Product, Deployments) referenced by the Project file
--files	-f	No	No	Also deletes all of the device and agent source code files referenced by the Project file
--all	-a	No	No	Includes --entities and --files options
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Project Info

impt project info [--full] [--output <mode>] [--help]

Displays information about the project. Fails if there is no Project file in the current directory. With every call the latest information is obtained using the impCentral API.

Informs the user if the Device Group referenced by Project file does not exist. The Project file is not deleted in this case. To delete it, call impt project delete.

Option	Alias	Mandatory?	Value Required?	Description
--full	-u	No	No	Displays additional information: full details about the corresponding Device Group as with impt dg info --full, and authentication status as with impt auth info
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Project Link

impt project link --dg <DEVICE_GROUP_IDENTIFIER> [--device-file <device_file>]
    [--agent-file <agent_file>] [--confirmed] [--output <mode>] [--help]

Creates a new Project file in the current directory and links it to the specified Device Group.

The command fails if:

• The specified Device Group does not exist or is not unique.
• The specified Device Group is not of the development or pre-factory type.

The user is asked to confirm the operation if the current directory already contains a Project file, unless confirmed automatically with the --confirmed option. If confirmed, the existing Project file is overwritten.

The command does not download any Deployment. To download source code from a Deployment, call impt build get.

At the end of the command execution, information about the Project is displayed as by impt project info.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes	Yes	A Device Group identifier
--device-file	-x	No	Yes	The device source code file name. Default: device.nut. If the file does not exist, an empty file is created
--agent-file	-y	No	Yes	The agent source code file name. Default: agent.nut. If the file does not exist, an empty file is created
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Project Update

impt project update [--name <device_group_name>] [--descr <device_group_description>]
    [--device-file <device_file>] [--agent-file <agent_file>]
    [--dut <DEVICE_GROUP_IDENTIFIER>] [--target <DEVICE_GROUP_IDENTIFIER>]
    [--output <mode>] [--help]

Updates the Project settings and/or the name, description, target device-under-test Device Group or target production Device Group of the Device Group referenced by the Project file. Fails if there is no Project file in the current directory.

Informs the user if the Device Group referenced by the Project file does not exist. The Project file is not updated or deleted in this case. To delete it, call impt project delete.

At the end of the command execution, information about the Project is displayed as by impt project info.

Option	Alias	Mandatory?	Value Required?	Description
--name	-n	No	Yes	The Project Device Group’s new name. Must be unique among all Device Groups in the Product
--descr	-s	No	Yes	The Project Device Group’s new description
--device-file	-x	No	Yes	A new device source code file name. If the file does not exist, an empty file is created
--agent-file	-y	No	Yes	A new agent source code file name. If the file does not exist, an empty file is created
--dut	-u	No	Yes	The Device Group identifier of the Project Device Group’s target device-under-test Device Group. May only be specified if the Project Device Group is of the pre-factory type. The specified Device Group must be of the type pre-dut and belong to the same Product as the Project Device Group. Otherwise the command fails
--target	-t	No	Yes	The Device Group identifier of the Project Device Group’s target production Device Group. May only be specified if the Project Device Group is of the pre-factory type. The specified Device Group must be of the type pre-production and belong to the same Product as the Project Device Group. Otherwise the command fails
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Test Commands

Test Create

impt test create --dg <DEVICE_GROUP_IDENTIFIER> [--device-file <device_file>]
    [--agent-file <agent_file>] [--timeout <timeout>] [--stop-on-fail [true|false]]
    [--allow-disconnect [true|false]] [--builder-cache [true|false]]
    [--test-file <test_file_name_pattern>] [--github-config <github_credentials_file_name>]
    [--builder-config <builder_file_name>] [--confirmed] [--output <mode>] [--help]

Creates a test configuration file in the current directory.

The user is asked to confirm the operation if the current directory already contains a test configuration file (confirmed automatically with the --confirmed option). If confirmed, the existing test configuration file is overwritten.

At the end of the command execution, information about the test configuration is displayed (as by impt test info).

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes	Yes	The Device Group identifier of the Device Group whose devices are used for test execution
--device-file	-x	No	Yes	A path to an optional file with device source code that is deployed along with the tests. A relative or absolute path can be used
--agent-file	-y	No	Yes	A path to an optional file with agent source code that is deployed along with the tests. A relative or absolute path can be used
--timeout	-t	No	Yes	A timeout period in seconds after which a test is interrupted and considered to have failed. Default: 30 seconds
--stop-on-fail	-s	No	No	If true or no value, the whole tests execution is stopped after a test failure. If false, the tests execution is not stopped after a failure. Default: false
--allow-disconnect	-a	No	No	If true or no value, keep a test session alive when a device is temporarily disconnected. If false, a test session fails when a device is disconnected. Default: false
--builder-cache	-e	No	No	If true or no value, cache external libraries in the local .builder-cache directory. If false, do not cache external libraries. If the local .builder-cache directory exists, it is cleaned. Default: false
--test-file	-f	No	Yes	Test file name or pattern. All files located in the current directory and all its sub-directories whose names match the specified name or pattern are considered as files with test cases. This option may be repeated multiple times to specify multiple names and/or patterns. The values of the repeated option are combined by logical OR. Default: "*.test.nut" "tests/**/*.test.nut"
--github-config	-i	No	Yes	A path to a GitHub credentials file. A relative or absolute path can be used. The specified file may not exist
--builder-config	-j	No	Yes	A path to a file with Builder variables. A relative or absolute path can be used. The specified file may not exist
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Test Delete

impt test delete [--github-config] [--builder-config] [--entities] [--all] [--confirmed]
    [--output <mode>] [--help]

Deletes the test configuration file in the current directory. Does nothing if there is no test configuration file in the current directory.

The following entities are deleted (if the exist):

• A test configuration file in the current directory.
• A Builder cache (.builder-cache directory) in the current directory.
• Debug information (.build directory) in the current directory.
• If the --github-config option is specified, the GitHub credentials file referenced by the test configuration file.
• If the --builder-config option is specified, the file with Builder variables referenced by the test configuration file.
• If the --entities option is specified:
  • The Device Group referenced by the test configuration file. All Devices are unassigned from that Device Group.
  • All builds (Deployments) of the Device Group referenced by the test configuration file, including Deployments with its flagged attribute set to true.
  • The Product which includes the Device Group referenced by the test configuration file. If the Product includes any additional Device Groups, the Product is not deleted (the operation is not considered a fail).

The user is asked to confirm the operation unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--github-config	-i	No	No	Also deletes the GitHub credentials file referenced by test configuration file
--builder-config	-j	No	No	Also deletes the file with Builder variables referenced by test configuration file
--entities	-e	No	No	Also deletes the impCentral API entities (Device Group, Product, Deployments) referenced by test configuration file. See above.
--all	-a	No	No	Includes --github-config, --builder-config and --entities options
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Test Github

impt test github --github-config <github_credentials_file_name> [--user <github_username>
    [--pwd <github_password>]] [--confirmed] [--output <mode>] [--help]

Creates or updates a GitHub credentials file.

Note This command does not write the created or updated GitHub credentials file to any test configuration file. Use impt test create or impt test update to apply the GitHub credentials to tests.

The user is asked to confirm the operation if the specified GitHub credentials file already exists, unless confirmed automatically with the --confirmed option. If confirmed, the existing GitHub credentials file is overwritten.

If the --user option is not specified, the user is asked to input the GitHub credentials. If the --user option is specified but the --pwd option is not, the user is asked to input the GitHub account password or personal access token.

Option	Alias	Mandatory?	Value Required?	Description
--github-config	-i	Yes	Yes	A path to the GitHub credentials file. A relative or absolute path can be used
--user	-u	No	Yes	A GitHub account username
--pwd	-w	No	Yes	A GitHub account password or personal access token. If specified, the --user option must also be specified
--confirmed	-q	No	No	Executes the operation without asking additional confirmation from user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Test Info

impt test info [--output <mode>] [--help]

Displays information about the test configuration defined by the test configuration file in the current directory. With every call, the latest actual information is obtained using the impCentral API.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Test Run

impt test run [--tests <test_pattern>] [--clear-cache] [--output <mode>] [--help]

Runs the tests specified by the test configuration file in the current directory.

Option	Alias	Mandatory?	Value Required?	Description
--tests	-t	No	Yes	A pattern to select the tests. Allows you to select specific test files, test cases and/or test methods for execution. The syntax of the pattern: [testFile][:testCase][::testMethod], where testFile may include a relative path as well as regular expressions. If the option is omitted, all tests from all test files specified in the test configuration file are executed
--clear-cache	-e	No	No	Clears the local .builder-cache directory if it exists
--output	-z	No	Yes	Adjusts the command’s output. Use --output debug to run the tests in debug mode
--help	-h	No	No	Displays a description of the command. Ignores any other options

Test Update

impt test update [--dg <DEVICE_GROUP_IDENTIFIER>] [--device-file [<device_file>]]
    [--agent-file [<agent_file>]] [--timeout <timeout>] [--stop-on-fail [true|false]]
    [--allow-disconnect [true|false]] [--builder-cache [true|false]]
    [--test-file <test_file_name_pattern>] [--github-config [<github_credentials_file_name>]]
    [--builder-config [<builder_file_name>]] [--output <mode>] [--help]

Updates the test configuration file in the current directory. Fails if there is no test configuration file in the current directory.

At the end of the command execution, information about the test configuration is displayed (as by impt test info).

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	No	Yes	The Device Group identifier of the Device Group whose devices are used for test execution
--device-file	-x	No	No	A path to a file with device source code that is deployed along with the tests. A relative or absolute path can be used. Specify this option without a value to remove this file from the test configuration
--agent-file	-y	No	No	A path to a file with agent source code that is deployed along with the tests. A relative or absolute path can be used. Specify this option without a value to remove this file from the test configuration
--timeout	-t	No	Yes	A timeout period in seconds after which a test is interrupted and considered as failed
--stop-on-fail	-s	No	No	If true or no value, the whole tests execution is stopped after a test failure. If false, the tests execution is not stopped after a failure
--allow-disconnect	-a	No	No	If true or no value, keep a test session alive when a device is temporary disconnected. If false, a test session fails when a device is disconnected
--builder-cache	-e	No	No	If true or no value, cache external libraries in the local .builder-cache directory. If false, do not cache external libraries; in this case, if the local .builder-cache directory exists, it is cleaned
--test-file	-f	No	Yes	Test file name or pattern. All files located in the current directory and all its sub-directories whose names match the specified name or pattern are considered as files with test cases. This option may be repeated multiple times to specify multiple names and/or patterns. The values of the repeated option are combined by logical OR. The specified values fully replace the existed setting
--github-config	-i	No	No	A path to a GitHub credentials file. A relative or absolute path can be used. The specified file may not exist. Specify this option without a value to remove a GitHub credentials file from the test configuration
--builder-config	-j	No	No	A path to a file with Builder variables. A relative or absolute path can be used. The specified file may not exist. Specify this option without a value to remove a file with Builder variables from the test configuration
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Webhook Manipulation Commands

Webhook Create

impt webhook create [--dg <DEVICE_GROUP_IDENTIFIER>] --url <target_url> --event <triggered_event>
    --mime <content_type> [--output <mode>] [--help]

Creates a new webhook for the specified Device Group.

Option	Alias	Mandatory?	Value Required?	Description
--dg	-g	Yes/Project	Yes	A Device Group identifier. If not specified, the Device Group referenced by the Project file in the current directory is used (if there is no Project file, the command fails)
--url	-u	Yes	Yes	The webhook’s target URL
--event	-e	Yes	Yes	The event that triggers the webhook. Valid values: "blessing", "blinkup", "deployment"
--mime	-m	Yes	Yes	The MIME content-type of the event data. Valid values: "json", "urlencoded"
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Webhook Delete

impt webhook delete --wh <webhook_id> [--confirmed] [--output <mode>] [--help]

Deletes the specified webhook.

The user is asked to confirm the operation unless confirmed automatically with the --confirmed option.

Option	Alias	Mandatory?	Value Required?	Description
--wh	-w	Yes	Yes	The webhook ID
--confirmed	-q	No	No	Executes the operation without asking for confirmation from the user
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Webhook Info

impt webhook info --wh <webhook_id> [--output <mode>] [--help]

Displays information about the specified webhook.

Option	Alias	Mandatory?	Value Required?	Description
--wh	-w	Yes	Yes	The Webhook ID
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Webhook List

impt webhook list [--owner <ACCOUNT_IDENTIFIER>] [--product <PRODUCT_IDENTIFIER>]
    [--dg <DEVICE_GROUP_IDENTIFIER>] [--dg-type <device_group_type>]
    [--url <target_url>] [--event <triggered_event>] [--output <mode>] [--help]

Displays information about all webhooks available to the current account.

The returned list of the webhooks may be filtered with any combination of the described filter options. Every filter option may be used multiple times. All filter options with the same name are combined by logical OR, then all filter options with different names are combined by logical AND.

Option	Alias	Mandatory?	Value Required?	Description
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

Filter Option	Alias	Mandatory?	Value Required?	Description
--owner	-o	No	Yes	Webhooks owned by the specified Account(s) only
--product	-p	No	Yes	Webhooks created for Device Groups which belong to the specified Product(s) only
--dg	-g	No	Yes	Webhooks created for the specified Device Group(s) only
--dg-type	-y	No	Yes	Webhooks created for Device Groups of the specified type only
--url	-u	No	Yes	Webhooks with the specified target URL only
--event	-e	No	Yes	Webhooks for the specified event only. Valid values: "blessing", "blinkup", "deployment"

Webhook Update

impt webhook update --wh <webhook_id> [--url <target_url>] [--mime <content_type>]
    [--output <mode>] [--help]

Updates the specified webhook with a new target URL and/or MIME content-type. Fails if the specified webhook does not exist.

Option	Alias	Mandatory?	Value Required?	Description
--wh	-w	Yes	Yes	The webhook ID
--url	-u	No	Yes	The webhook’s new target URL
--mime	-m	No	Yes	New MIME content-type of the event data. Valid values: "json", "urlencoded"
--output	-z	No	Yes	Adjusts the command’s output
--help	-h	No	No	Displays a description of the command. Ignores any other options

List Of Aliases

Command Option Alias	Command Option Full Name(s)
-a	--all, --assigned, --allow-disconnect
-b	--build, --builds
-c	--create-product, --conditional
-d	--device
-e	--endpoint, --entities, --event, --builder-cache, --clear-cache
-f	--force, --files, --pre-factory, --from, --flagged, --offline, --test-file
-g	--dg
-h	--help
-i	--device-only, --github-config
-j	--agent-only, --builder-config
-k	--lk
-l	--log, --local, --load-code-after-blessing
-m	--min-supported-deployment, --mime, --zombie
-n	--name, --online, --page-number, --non-zombie
-o	--owner, --origin, --unflag-old
-p	--product
-q	--confirmed
-r	--create-target, --remove-tag, --remove, --region
-s	--descr, --sha, --page-size, --stop-on-fail
-t	--tag, --timeout, --temp, --target, --to, --tests
-u	--user, --full, --unflagged, --unflag, --unassigned, --unbond, --url, --dut
-v	--version
-w	--wh, --pwd, --create-dut
-x	--device-file
-y	--agent-file, --dg-type
-z	--output

Common Filter Options

Filter Option	Alias	Value	Description
--owner	-o	<ACCOUNT_IDENTIFIER>	Entities owned by the specified Account only
--product	-p	<PRODUCT_IDENTIFIER>	Entities related to the specified Product only
--dg	-g	<DEVICE_GROUP_IDENTIFIER>	Entities related to the specified Device Group only
--dg-type	-y	<device_group_type>	Entities related to the Device Groups of the specified type only