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 Migrates the current tenant to one that supports role-based access control. Not supported in the new Azure Sphere CLI.
select Selects the default Azure Sphere tenant to use on this computer.
show-selected Shows the default Azure Sphere tenant for this computer.

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. The tenant name cannot 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 to run the command on when multiple devices are attached. This is only required when multiple devices are attached. The currently attached device is used by default. You can either specify the ID, IP address, or Local Connection ID of the attached device. 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 Tenant1

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 Tenant2 --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 'Tenant2' 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: Tenant2
 --> Tenant ID:   183adhc9-a5c8-8he2-84a2-c4f00f73a471
Please use 'azsphere tenant select --tenant Tenant2' 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.

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 a323c263-2aa3-2559-aabb-a3fc32631900

list

Lists Azure Sphere tenants.

Once the tenant has been migrated to role-based access control, azsphere tenant list will display only the tenants for which you have a defined role.

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
 ========================================================================
 a323c263-2aa3-2559-aabb-a3fc32631900 Tenant1               Administrator
                                                            Contributor
 ------------------------------------ --------------------- -------------

migrate

Performs a one-time migration of a tenant to support role-based access control (RBAC) and new device model.

When you create a new tenant, your user identity is automatically made an administrator of the tenant. You can then register or add other users and give them roles in the tenant.

The azsphere tenant migrate command is used once per tenant to migrate to RBAC support, required as of the 19.10 release or later. The command will attempt to find your current user credential for your tenant (if you have one and have logged on). If you have more than one tenant you will be prompted to select the correct tenant to migrate. If the tenant cannot be located, or your credentials cannot be determined, use the optional --force-prompt parameter to be prompted for the tenant name and your credentials.

Note

This command is not supported in Azure Sphere CLI.

Optional parameters

Parameter Type Description Supported version
-f, --force-legacy-login - Requires a legacy account to be manually selected. Azure Sphere classic CLI
-i, --tenantid GUID Specifies the ID of the Azure Sphere tenant to migrate. 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

This command is not supported in Azure Sphere CLI.

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 a323c263-2aa3-2559-aabb-a3fc32631900
 ------------------------------------ --------------------- -------------
 Id                                   Name                  Roles
 ========================================================================
 a323c263-2aa3-2559-aabb-a3fc32631900 Tenant1               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
 ========================================================================
 a323c263-2aa3-2559-aabb-a3fc32631900 Tenant1               Administrator
                                                            Contributor
 ------------------------------------ --------------------- -------------