tenant
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.
Manages an Azure Sphere tenant.
Important
The commands azsphere tenant download-ca-certificate, azsphere tenant download-ca-certificate-chain, and azsphere tenant download-validation-certificate are obsolete. Use azsphere ca-certificate download, azsphere ca-certificate download-chain, azsphere ca-certificate download-proof, and azsphere ca-certificate list instead.
In the Azure Sphere CLI, the default tenant is not automatically selected when a tenant is created. You have to run the azsphere tenant select command to select the default tenant to use for the current user on the PC. This is to ensure that the default tenant is the correct one to use when performing a one-time operation that you cannot undo, like claiming the device.
| Operation | Description |
|---|---|
| create | Creates a new tenant. |
| download-error-report | Returns error information for devices within the current tenant. |
| list | Lists the available Azure Sphere tenants. |
| select | Selects the default Azure Sphere tenant to use on this computer. |
| show-selected | Shows the default Azure Sphere tenant for this computer. |
| update | Updates the tenant's details, such as the name of the tenant. |
create
Creates a new Azure Sphere tenant. An attached device is required to run this command. For more information, see Create an Azure Sphere tenant.
If you already have a tenant and are certain you want another one, use the --force-additional parameter. Currently, you cannot delete an Azure Sphere tenant.
Once the tenant is created, run azsphere tenant select to select the default tenant to use for the current user on this PC. You can add roles for users in the current Azure Sphere tenant using the azsphere role add command.
The azsphere tenant create command works with a locally attached Azure Sphere device. If you attempt the command without a device attached you will receive an error. The device ID is recorded when you create a tenant, and only one tenant can be created per device.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| -n, --name | String | Specifies a name for the tenant. When naming your tenant, use alphanumeric characters. Special characters are not allowed. The name must not exceed 50 characters and is case sensitive. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| -d, --device | String | Specifies the device on which to run the command when multiple devices are attached. This parameter is required when multiple devices are attached. The currently attached device is used by default. You can specify the device ID, IP address, or Local Connection ID of the attached device. Azure Sphere CLI supports multiple MT3620 devices on Windows, but you can connect only one device at a time on Linux. For this reason, this parameter is supported for Windows but not for Linux. An error is returned if you use this parameter with the command on Linux. |
| --force-additional | Boolean | Forces creation of a new Azure Sphere tenant. Use this command only if you are certain that you want to use the current account to create a new Azure Sphere tenant using the attached device. |
| --disable-confirm-prompt | Boolean | Disables the user confirmation prompt. |
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 tenant create --name MyTenant
Use the --force-additional and --disable-confirm-prompt parameters if you are certain that you want to use this account to create a new Azure Sphere tenant using the attached device. A device that has previously been used to create an Azure Sphere tenant cannot be used to create a new tenant.
azsphere tenant create --name MyTenant --force-additional
You have logged in with the following account:
bob@contoso.com
Do you want to use this account to create a new Azure Sphere tenant using the attached device?
You cannot change the tenant name 'MyTenant1' once it has been created.
Enter 'yes' to continue. Enter anything else to exit.
yes
> verbose: TraceId: c761ba73-761e-4df2-94f5-3f87384d71b7
Created a new Azure Sphere tenant:
--> Tenant Name: MyTenant1
--> Tenant ID: 768c2cd6-059a-49ad-9f53-89f5271cea15
Please use 'azsphere tenant select --tenant MyTenant' to select the created tenant.
Tip
Once you have created a tenant make sure you run azsphere tenant select to select the default tenant to use for the current user on this PC.
download-error-report
Returns information on errors reported by devices within the current tenant.
This command pulls event data from the Azure Sphere Security Service cloud and does not require a physical connection to a particular device. The azsphere tenant download-error-report command works in the context of the current tenant and returns error reports for all devices within that tenant.
Note
It may take up to 24 hours for recently reported events to be available for download. For more information, see Collect and interpret error data.
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| --destination | String | Specifies the path and filename of the output file. |
| -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 tenant download-error-report --destination c:\error-report.csv --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
list
Lists Azure Sphere tenants.
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 tenant list
------------------------------------ --------------------- -------------
Id Name Roles
========================================================================
143adbc9-1bf0-4be2-84a2-084a331d81cb MyTenant Administrator
Contributor
------------------------------------ --------------------- -------------
select
Selects the default Azure Sphere tenant to use for the current user on this PC.
To display the current default tenant, use azsphere tenant show-selected.
Required 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 tenant select --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
------------------------------------ --------------------- -------------
Id Name Roles
========================================================================
143adbc9-1bf0-4be2-84a2-084a331d81cb MyTenant Administrator
Contributor
------------------------------------ --------------------- -------------
show-selected
Displays the details of the default Azure Sphere tenant for the current user on this PC.
This is the tenant selected with the azsphere tenant select command.
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 tenant show-selected
------------------------------------ --------------------- -------------
Id Name Roles
========================================================================
143adbc9-1bf0-4be2-84a2-084a331d81cb MyTenant Administrator
Contributor
------------------------------------ --------------------- -------------
update
Updates a tenant's details, such as the name of the tenant.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| -n, --new-name | String | Specifies a new name for the tenant. When naming your tenant, use alphanumeric characters. Special characters are not allowed. The name must not exceed 50 characters and is case sensitive. |
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 tenant update --tenant a323c263-2aa3-2559-aabb-a3fc32631900 --new-name Tenant2
------------------------------------ --------------------- -------------
Id Name Roles
========================================================================
a323c263-2aa3-2559-aabb-a3fc32631900 Tenant2 Administrator
Contributor
------------------------------------ --------------------- -------------
Tip
If you have not selected a default tenant, a list of available tenants is displayed. Set your default tenant by selecting one of the options.