Overview of Azure Sphere CLI

  • Article

The Azure Sphere CLI is a set of commands used to manage your Azure Sphere resources.

The following commands are available:

Azure Sphere CLI and Azure Sphere classic CLI

The Azure Sphere CLI is installed alongside the existing CLI on both Windows and Linux, so you have access to either interface. The Azure Sphere classic CLI continues to work as it always has.

To use the Azure Sphere CLI:

  • On Windows, use PowerShell or a standard Windows Command Prompt.
  • On Linux, use any command shell. Specify the azsphere command if you set Azure Sphere CLI as the default during SDK installation, or the azsphere_v2 command if you set the Azure Sphere classic CLI as the default.

See Azure Sphere CLI for details about the features and commands supported by Azure Sphere CLI.

Important

  • On Windows, the retiring Azure Sphere Classic Developer Command Prompt shortcut can only be used with Azure Sphere classic CLI.

Command-line format

The azsphere command line has the following format:

azsphere [command] [subcommand] operation [parameters]

In general, command and subcommand are nouns and operation is a verb, so that the combination identifies both an action and the object of the action. Most commands and operations have both a full name and an abbreviation. For example, the device command is abbreviated d.

Most parameters have both a long name and an abbreviation. On the command line, introduce the long name with two hyphens and the abbreviation with a single hyphen. For example, the following two commands are equivalent:

azsphere device wifi add --ssid MyNetwork --psk mynetworkkey

azsphere device wifi add -s MyNetwork -p mynetworkkey

Some commands allow multiple values for a single parameter. In Azure Sphere CLI you can supply a single parameter followed by a list of values separated by spaces and in the Azure Sphere classic CLI the list of values are separated by commas. For example:

azsphere image-package pack-application --package-directory myDirectory --destination myImagePackage --executables filepath-1 filepath-2

Quotation marks and escapes characters

When you work with Azure Sphere CLI commands, be aware of how your shell uses quotation marks and escapes characters. If you support scripts used in different shells, you need to understand how they differ.

For example:

Cloud-dependent commands

The following azsphere commands require a cloud connection and login to the Azure Sphere Security Service:

  • ca-certificate
  • device-group
  • get-support-data
  • image
  • login
  • logout
  • product
  • register-user
  • role
  • show-user
  • tenant

In addition, the following azsphere device commands also require a cloud connection:

azsphere device command Comments
capability Requires Azure Sphere Security Service for device capability download
claim
enable-cloud-test
enable-development
image
list
recover Requires internet connectivity, but not login to Azure Sphere Security Service
show
show-count
show-deployment-status
show-os-version Requires internet connectivity, but not login to Azure Sphere Security Service
update

Device capability-dependent commands

The following azsphere device commands require a device capability be used for devices in manufacturing state DeviceComplete:

Operation Description
app Manage applications on the attached device.
capability Manage device capability configurations. Required for capability update.
certificate Manage device certificate store.
image Manage device images.
manufacturing-state Manage the manufacturing state of attached devices. Required for manufacturing-state update.
restart Restart the attached device.
show-deployment-status Show the deployment status of the operating system and applications on the attached device.
show-os-version Show the operating system version on the attached device.
sideload Deploy and manage applications on the attached device. Required for sideload deploy and sideload delete.
wifi Manage Wi-Fi configurations for the attached device.

If you attempt to run these commands without a capability, you receive an error message telling you to either run azsphere device enable-development or use azsphere device capability to download and select a capability file for the device.