tenant

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. Use Azure Sphere classic CLI to run this command.
download-error-report Returns error information for devices within the current tenant.
list Lists the available Azure Sphere tenants.
migrate Not supported.
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 Supported version
-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. - Azure Sphere CLI
- Azure Sphere classic CLI

Optional parameters

Parameter Type Description Supported version
-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.
Azure Sphere CLI
--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. Azure Sphere CLI
--disable-confirm-prompt Boolean Disables the user confirmation prompt. Azure Sphere CLI
-ip, --deviceip String (Multi-device, Windows only) Specifies the IP address of the device to use for this operation.
This is only required when multiple devices are attached. You can specify either a device IP or device location.
Azure Sphere classic CLI
-l, --devicelocation String (Multi-device, Windows only) Specifies the FTDI location ID of the device to use for this operation.
This is only required when multiple devices are attached. You can specify either a device IP or device location.
Azure Sphere classic CLI
--force 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. Azure Sphere classic CLI
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 Supported version
--destination String Specifies the path and filename of the output file. Azure Sphere CLI
-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. Azure Sphere CLI
-o, --output String Specifies the path and filename of the output file. Azure Sphere classic CLI
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
 ------------------------------------ --------------------- -------------

migrate

Note

This command is not supported.

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 Supported version
-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. Azure Sphere CLI
-i, --tenantid GUID Specifies the ID of the Azure Sphere tenant to select as the default on this PC. Azure Sphere classic CLI
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 Supported version
-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. Azure Sphere CLI

Optional parameters

Parameter Type Description Supported version
-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. Azure Sphere CLI
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.