device-group

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

Creates and manages device groups.

Device groups are addressed either by identifier (ID) or by a product name and device group name pair.

Operation Description
create Creates a new device group.
list List all device groups in your Azure Sphere tenant.
delete Deletes an existing device group.
deployment Manages deployments within a device group.
device Lists devices in a device group.
show Displays information about a device group.
update Modifies an existing device group.

create

Creates a device group with the specified name for the specified product. The device group organizes devices that have the same product and receive the same applications from the cloud.

Required parameters

Parameter Type Description
-p, --product GUID or name Specifies the product to add this device group to. You can specify either the ID or name of the Azure Sphere product.
-n, --name String Specifies a name for the device group. The name can only include alphanumeric characters. If the name includes spaces, enclose it in quotation marks. The device group name cannot exceed 50 characters, is case insensitive, must be unique within the product.

Optional parameters

Parameter Type Description
-a, --application-update Enum Specifies the application update policy to apply for this device group. Accepted values: No3rdPartyAppUpdates, UpdateAll, and NoUpdates. Default is UpdateAll. The NoUpdates policy is currently reserved for internal use only.
-f, --os-feed Enum Specifies the OS feed type to use for OS updates. Accepted values: Retail, RetailEval.
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
-d, --description String Specifies the optional text to describe the device group. The maximum length is 100 characters. If the description includes spaces, enclose it in quotation marks.
-r, --regional-data-boundary String Regional data boundary for this image. Allowed values: EU, None. The default value is None. If no value is specified the default value will be used. For more information, see Configure crash dumps - Pivacy considerations
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere device-group create --name Marketing --product DW100

 ------------------------------------ ------------------------------------ ---------- ------------------------------------ ---------- ---------------------------------------------------------- ----------------------------- ---------------------
 Id                                   TenantId                             OsFeedType ProductId                            Name       UpdatePolicy                                               AllowCrashDumpsCollection     RegionalDataBoundary
 ===================================================================================================================================================================================================================================================
 7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb Retail     6f52bead-700d-4289-bdc2-2f11f774270e Marketing Accept all updates from the Azure Sphere Security Service. False                          None
 ------------------------------------ ------------------------------------ ---------- ------------------------------------ ---------- ---------------------------------------------------------- ----------------------------- --------------------

list

List all device groups in your Azure Sphere tenant.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere device-group list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb

  ------------------------------------ ------------------------ --------------------------------------------- ------------------------------------ ---------- ---------------------------------------------------------------------- ----------------------------- ---------------------
 Id                                   Name                     Description                                   ProductId                            OsFeedType UpdatePolicy                                                           AllowCrashDumpsCollection     RegionalDataBoundary
 =====================================================================================================================================================================================================================================================================================
 a3a49688-4601-4422-8b51-a0838ea84627 Development              Default development device group              6f52bead-700d-4289-bdc2-2f11f774270e Retail     Accept only system software updates. Don't accept application updates. False                         None
 ------------------------------------ ------------------------ --------------------------------------------- ------------------------------------ ---------- ---------------------------------------------------------------------- ----------------------------- --------------------
 7cb46b96-8c17-4afd-bd3f-614acad9d264 Field Test               Default test device group                     6f52bead-700d-4289-bdc2-2f11f774270e Retail     Accept all updates from the Azure Sphere Security Service.             False                         None
 ------------------------------------ ------------------------ --------------------------------------------- ------------------------------------ ---------- ---------------------------------------------------------------------- ----------------------------- --------------------
 30c39bae-f525-4094-8008-d03705429ef0 Production               Default production device group               6f52bead-700d-4289-bdc2-2f11f774270e Retail     Accept all updates from the Azure Sphere Security Service.             False                         None
 ------------------------------------ ------------------------ --------------------------------------------- ------------------------------------ ---------- ---------------------------------------------------------------------- ----------------------------- --------------------
 cb5c9685-5dbe-470c-91a9-91dc129884d6 Production OS Evaluation Default Production OS Evaluation device group 6f52bead-700d-4289-bdc2-2f11f774270e RetailEval Accept all updates from the Azure Sphere Security Service.             False                         None
 ------------------------------------ ------------------------ --------------------------------------------- ------------------------------------ ---------- ---------------------------------------------------------------------- ----------------------------- --------------------
 63e72035-3fcf-4fdc-b88a-05e30d1ba224 Field Test OS Evaluation Default Field Test OS Evaluation device group 6f52bead-700d-4289-bdc2-2f11f774270e RetailEval Accept all updates from the Azure Sphere Security Service.             False                         None
 ------------------------------------ ------------------------ --------------------------------------------- ------------------------------------ ---------- ---------------------------------------------------------------------- --------------------------------------------------

delete

Deletes the specified device group in your Azure Sphere tenant.

A device group can only be deleted when:

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group to delete. You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

azsphere device-group delete --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd
Successfully deleted the device group
azsphere device-group delete --device-group DW100/Development
Successfully deleted the device group

deployment

Manages deployments for a device group.

Operation Description
create Creates a new deployment for the specified device group.
list Displays the deployments for a device group.

deployment create

Creates a new deployment for a device group with the supplied images.

You can identify the device group either by identifier (ID) or by a product name and device group name pair.

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group in which to create the deployment. You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.
-i, --images String Specifies the image IDs for one or more images to include in the deployment. You can add multiple images by adding additional parameters, or multiple image IDs can be combined in a single parameter in a space-separated list. Run the azsphere image add command to get the image ID.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

The --device-group parameter identifies the device group. The device group ID supplies a GUID, which uniquely identifies the device group across all products. Alternatively, you can use the product name and device group name pair in the <product-name>/<device-group-name> format. This pair of names uniquely identifies a device group for a particular product.

Example to specify device group by ID:

azsphere device-group deployment create --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd --images 5572509b-43a4-45b0-88c5-365cbf9732c1

Example to specify device group by name:

azsphere device-group deployment create --device-group DW100/Development --images 5572509b-43a4-45b0-88c5-365cbf9732c1

Example to specify multiple image IDs by providing a list of values separated by spaces:

azsphere device-group deployment create --device-group DW100/Development --images 5572509b-43a4-45b0-88c5-365cbf9732c1 3bbd2d2a-2870-4dde-9db8-ae50548ea7b4

You should see output like this:

------------------------------------ ------------------------------------ ------------------------------------ ------------------------------------
Id                                   TenantId                             DeployedImages                       DeploymentDateUtc                    
===================================================================================================================================================
7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb 5572509b-43a4-45b0-88c5-365cbf9732c1 2021-04-01T18:48:41.721662+00:00     
------------------------------------ ------------------------------------ ------------------------------------ ------------------------------------

deployment list

Displays the deployment history for a device group. Returns the deployment ID, timestamp, and list of included images. The list is ordered by most recent deployments.

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group for which to display the deployment history list. You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

Example to specify device group by ID:

azsphere device-group deployment list --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd

Example to specify device group by name:

azsphere device-group deployment list --device-group DW100/Development

You should see output like this:

------------------------------------ ------------------------------------ ------------------------------------ ------------------------------------
Id                                   TenantId                             DeployedImages                       DeploymentDateUtc                   
===================================================================================================================================================
7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb e3769536-dc4b-48d9-afd4-22ed321ba4bc 2020-11-18T19:46:50.514429+00:00    
------------------------------------ ------------------------------------ ------------------------------------ ------------------------------------

device

Manages devices for a device group.

Operation Description
list Displays the devices in a device group.
show-count Shows the number of devices in a device group.

device list

Displays the devices in a device group.

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group for which to display the device list. You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

Example to specify device group by ID:

azsphere device-group device list --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd

Example to specify device group by name:

azsphere device-group device list --device-group DW100/Marketing

You should see output like this:

-------------------------------------------------------------------------------------------------------------------------------- ------------------------------------ ------------------------------------ ----------------------------------------
DeviceId                                                                                                                         TenantId                             ProductId                            DeviceGroupId                           
===================================================================================================================================================================================================================================================
352FE1F59E40EF8A9266415E81AF32B5B07D8F2BBD6B5650CEF4A70B86C7FCBC70B129A41FBC6D02F8BB4AAABC52CD5740C85427D205E46A166B7E41135EB968 143adbc9-1bf0-4be2-84a2-084a331d81cb 6f52bead-700d-4289-bdc2-2f11f774270e 7f860cc1-4949-4000-a541-9a988ba4c3cd    
-------------------------------------------------------------------------------------------------------------------------------- ------------------------------------ ------------------------------------ ----------------------------------------

device show-count

Displays the number of devices in a device group.

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group for which to show the device count. You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

Example to specify device-group by ID:

azsphere device-group device show-count --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd

Example to specify device-group by name:

azsphere device-group device show-count --device-group DW100/Marketing

You should see output like this:

------
Result
======
1
------

show

Returns information about a device group.

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group for which to display details. You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.

Optional parameters

Parameter Type Description
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

Example to specify device-group by ID:

azsphere device-group show --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd

Example to specify device-group by name:

azsphere device-group show --device-group DW100/Marketing

You should see output like this:

------------------------------------ --------- ---------------------- ------------------------------------ ------------------------------------ ---------- ---------------------------------------------------------- ----------------------------- --------------------
Id                                   Name      Description            TenantId                             ProductId                            OsFeedType UpdatePolicy                                               AllowCrashDumpsCollection     RegionalDataBoundary
========================================================================================================================================================================================================================================================================
7f860cc1-4949-4000-a541-9a988ba4c3cd Marketing Marketing device group 143adbc9-1bf0-4be2-84a2-084a331d81cb 6f52bead-700d-4289-bdc2-2f11f774270e Retail     Accept all updates from the Azure Sphere Security Service. False                         None                         
------------------------------------ --------- ---------------------- ------------------------------------ ------------------------------------ ---------- ---------------------------------------------------------- ----------------------------- --------------------     

update

Updates an existing device group, identified by ID or by product name and device group name pair.

Required parameters

Parameter Type Description
-g, --device-group String Specifies the device group for which to update details.You can specify either the device group ID or the device group name. To use the device group name, you must provide both the product name and device group name in the <product-name/device-group-name> format.

Optional parameters

Parameter Type Description
-c, --allow-crash-dumps-collection String Set consent for collection of crash dumps by Microsoft for the device-group. Default is Off. Allowed values: Off and On. Use the --regional-data-boundary parameter to specify where the crash dump files should be stored. For more information, see Configure crash dumps.
-a, --application-update ApplicationUpdatePolicyType Specifies the application update policy for the device group. Allowed values: No3rdPartyAppUpdates, UpdateAll, and NoUpdates. Default is UpdateAll. The NoUpdates policy is currently reserved for internal use only.
-d, --new-description String Specifies optional text to describe the device group. The maximum length is 100 characters.
-n, --new-name String Specifies a new name for the device group. The name can only include alphanumeric characters. If the name includes spaces, enclose it in quotation marks. The device group name cannot exceed 50 characters, is case insensitive, and must be unique within the product.
-f, --os-feed String Specifies the operating system feed for the device group. Possible values are Retail and RetailEval.
-t, --tenant GUID or name Specifies the tenant to perform this operation in. Overrides the default selected tenant. You can specify either the tenant ID or tenant name.
-r, --regional-data-boundary String Regional data boundary for this image. Allowed values: EU, None. The default value is None. If no value is specified the default value will be used. For more information, see Configure crash dumps - Pivacy considerations
Global parameters

The following global parameters are available for the Azure Sphere CLI:

Parameter Description
--debug Increases logging verbosity to show all debug logs. If you find a bug, provide output generated with the --debug flag on when submitting a bug report.
-h, --help Prints CLI reference information about commands and their arguments and lists available subgroups and commands.
--only-show-errors Shows only errors, suppressing warnings.
-o, --output Changes the output format. The available output formats are json, jsonc (colorized JSON), tsv (Tab-Separated Values), table (human-readable ASCII tables), and yaml. By default the CLI outputs table. To learn more about the available output formats, see Output format for Azure Sphere CLI commands.
--query Uses the JMESPath query language to filter the output returned from Azure Sphere Security Services. See JMESPath tutorial and Query Azure CLI command output for more information and examples.
--verbose Prints information about resources created in Azure Sphere during an operation and other useful information. Use --debug for full debug logs.

Note

If you are using Azure Sphere classic CLI, see Global parameters for more information on available options.

Example

Example to specify device-group by ID:

azsphere device-group update --device-group 7f860cc1-4949-4000-a541-9a988ba4c3cd --new-description "Marketing device group"

Example to specify device-group by name:

azsphere device-group update --device-group DW100/Marketing --new-description "Marketing device group"

You should see output like this:

------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- ----------------------------- --------------------
Id                                   TenantId                             OsFeedType ProductId                            Name      Description            UpdatePolicy                                               AllowCrashDumpsCollection     RegionalDataBoundary
========================================================================================================================================================================================================================================================================
7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb Retail     6f52bead-700d-4289-bdc2-2f11f774270e Marketing Marketing device group Accept all updates from the Azure Sphere Security Service. False                         None
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- ----------------------------- --------------------