Overview of the Azure Sphere extension for Azure CLI

  • Article

The command-line tool for managing Azure Sphere attached devices and cloud deployments is distributed as an Azure CLI extension.

Install the Azure CLI and the Azure Sphere extension

To acquire the Azure Sphere extension for Azure CLI:

  1. Install the Azure CLI if you have not yet done so.

  2. To add the Azure Sphere extension, run the following command:

    az extension add --name azure-sphere

You must Sign in with Azure CLI to log into the Azure subscription you wish to use to manage Azure Sphere devices.

Once an extension is installed, its location is found under the value of the $AZURE_EXTENSION_DIR shell variable. If this variable is unset, by default the value is $HOME/.azure/cliextensions on Linux and macOS, and %USERPROFILE%\.azure\cliextensions on Windows.

Tip

After logging in, you will see a list of subscriptions associated with your Azure account. Ensure that you select the subscription with the required permissions using the az account set command for the Azure Sphere extension to function correctly. For more information about subscription selection, see Use multiple Azure subscriptions.

Managing the Azure Sphere extension

To see the installed versions of Azure CLI extensions, use the command:

az version

To update the Azure Sphere extension to the latest version, use:

az extension update --name azure-sphere

To uninstall the Azure Sphere extension, use:

az extension remove --name azure-sphere

Common Azure Sphere CLI commands

You can use Azure Sphere commands by typing az sphere from either Windows command prompt or PowerShell. On Linux, you can use any command-line interface (CLI). The CLI has full tab completion for commands under the bash shell.

This table lists some common Azure Sphere commands and links to their reference documentation.

Command Description
az sphere catalog Manage your catalog.
az sphere ca-certificate Manage certificates in your catalog.
az sphere deployment Manage deployments in your catalog.
az sphere device Manage Azure Sphere devices.
az sphere device-group Manage device groups in your catalog.
az sphere image Manage images in your catalog.
az sphere product Manage products in your catalog.
az sphere get-support-data Gather diagnostic data about your system, cloud and device configurations.

Azure CLI allows you to set up configuration options which simplify use of Azure Sphere CLI commands by providing defaults for parameters like the --resource-group, --subscription, or --catalog.

Device dependent commands

The command works with a locally attached Azure Sphere device. If you attempt the command without a device attached you will receive an error. For more information on device commands see, az sphere device

  • az sphere device claim
  • az sphere device recover
  • az sphere device restart
  • az sphere device show-attached
  • az sphere device show-os-version
  • az sphere device app show-memory-status
  • az sphere device app show-quota
  • az sphere device app show-status
  • az sphere device app start
  • az sphere device app stop
  • az sphere device capability show-attached
  • az sphere device capability update
  • az sphere device certificate add
  • az sphere device certificate delete
  • az sphere device certificate list
  • az sphere device certificate show
  • az sphere device certificate show-quota
  • az sphere device image list-installed
  • az sphere image-package show
  • az sphere device manufacturing-state show
  • az sphere device manufacturing-state update
  • az sphere device network proxy apply
  • az sphere device network proxy delete
  • az sphere device network proxy show
  • az sphere device network disable
  • az sphere device network enable
  • az sphere device network list-firewall-rules
  • az sphere device network list-interfaces
  • az sphere device network show-diagnostics
  • az sphere device network show-status
  • az sphere device network update-interface
  • az sphere device sideload delete
  • az sphere device sideload deploy
  • az sphere device wifi add
  • az sphere device wifi disable
  • az sphere device wifi enable
  • az sphere device wifi forget
  • az sphere device wifi list
  • az sphere device wifi reload-config
  • az sphere device wifi scan
  • az sphere device wifi show
  • az sphere device wifi show-status

Globally available arguments

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

Parameter Description
--debug Increase logging verbosity to show all debug logs.
--help -h Shows the help message.
--only-show-errors Only shows errors, suppressing warnings.
--output -o Output format. Allowed values: json, jsonc, none, table, tsv, yaml, yamlc. Default: json.
--query JMESPath query string. See http://jmespath.org/ for more information and examples.
--subscription : Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.
--verbose Increase logging verbosity. Use --debug for full debug logs.