Overview of azsphere

The Azure Sphere command-line utility is a set of commands used to manage your Azure Sphere resources.

The following commands are available:

Using CLI v1 and CLI v2 Beta

The CLI v2 Beta is installed alongside the existing CLI on both Windows and Linux, so you have access to either interface. The original v1 CLI continues to work as it always has.

To use CLI v2 Beta:

  • On Windows, use PowerShell or a standard Windows command prompt.
  • On Linux, use any command shell. Specify the azsphere command if you set CLI v2 Beta as the default during SDK installation, or the azsphere_v2 command if you set the v1 CLI as the default.

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

Important

  • On Windows, the Azure Sphere Developer Command Prompt shortcut can only be used with CLI v1.
  • The azsphere reference documentation has been updated to include details of available parameters and examples for both version. We also present examples for both versions in the Quickstarts and Tutorials. However, examples elsewhere in the documentation still reflect the original CLI v1.

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-group command is abbreviated dg.

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 which case you can either supply a parameter with each value, or a single parameter followed by a list of values separated by commas and no intervening spaces. For example, the following two commands are equivalent:

azsphere image-package pack-application --input myDirectory --output myImagePackage --executables filepath-1 --executables filepath-2

azsphere image-package pack-application --input myDirectory --output myImagePackage --executables filepath-1,filepath-2

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
  • img, image
  • login
  • logout
  • prd, product
  • register-user
  • role
  • show-user
  • tenant

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

azsphere device command Comments
cap, capability Requires Azure Sphere Security Service for device capability download
claim
enable-cloud-test
enable-development
img, 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:

Operation Description
app Manage applications on the attached device.
cap, capability Manage device capability configurations. Required for capability show, capability update, and capability download --apply.
cert, certificate Manage device certificate store.
img, image Manage device images.
mfg, manufacturing-state Manage the manufacturing state of attached devices.
recover Use recovery mode to load new firmware onto the device.
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.
sl, sideload Deploy and manage applications on the attached device.
wifi Manage Wi-Fi configurations for the attached device.

Troubleshoot script execution on Windows command prompt

You can execute a script containing a series of commands on PowerShell, Azure Sphere Developer Command Prompt, Linux command shell, or a standard Windows command prompt. However, in a standard Windows command prompt the script is terminated after the first command is executed. To resolve this, you must add call or cmd /c in front of each command. For example:

Use the following format to use call:

call azsphere show-version
call azsphere tenant show-selected
call azsphere show-user

Use the following format to use cmd /c:

cmd /c show-version
cmd /c tenant show-selected
cmd /c show-user