Share via

Azure Sphere CLI

  • Article

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

The Azure Sphere SDK provides the Azure Sphere command-line interface (CLI) available on PowerShell, Windows Command Prompt, or Linux command shell. The Azure Sphere CLI is a set of commands used to create and manage Azure Sphere resources.

The Azure Sphere CLI is installed alongside the retiring Azure Sphere classic CLI on both Windows and Linux, so you have access to either interface. To use Azure Sphere CLI:

  • On Windows, use PowerShell or a standard Windows Command Prompt.
  • On Linux, use any command shell.

Run the Azure Sphere CLI

You can now run the Azure Sphere CLI with the azsphere command from either Windows Command Prompt or PowerShell. We recommend PowerShell as it offers the tab completion feature which is not available from the Windows Command Prompt.

On Linux, you can run Azure Sphere CLI from any command-line interface (CLI). During installation, a notification is displayed that allows you to set Azure Sphere CLI or Azure Sphere classic CLI as the preferred default CLI version. Type Yes to choose Azure Sphere CLI or type No to use Azure Sphere classic CLI. See Install the Azure Sphere SDK for more information.

Note

The short form for commands is not supported in the Azure Sphere CLI version. We recommend that you use the tab completion feature to view the list of available commands. On Windows, the retiring Azure Sphere Classic Developer Command Prompt shortcut can only be used with Azure Sphere classic CLI.

CLI input features

This section describes the input features available in the Azure Sphere CLI:

Commands

All commands in the Azure Sphere CLI start with azsphere. For example:

azsphere login
 ---------------------
 Name
 =====================
 bob@contoso.com
 ---------------------

Find commands

Commands in the CLI are organized in groups. You can view full help information for the available commands and parameters by using --help in Azure Sphere classic CLI and Azure Sphere CLI.

You can get a full list of commands by running the command azsphere --help.

For example:

  • For Azure Sphere classic CLI use, azsphere --help or azsphere -?
  • For Azure Sphere CLI use, azsphere --help or azsphere -h

Parameters

The name of the parameter is preceded by double hyphens (--), which signals that the word following the hyphen is a parameter. Use a space to separate the parameter name and value. The parameters that are compound words are separated with a hyphen (-) in the new CLI.

For example: --component-id or --application-update

Simplified object identification

In the Azure Sphere CLI a single parameter is used to identify each object type. This means that you can provide either the ID, name, IP, or location applicable for that parameter.

For example, you can use either the tenant ID or tenant name in the following command:

azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb

or

azsphere device list --tenant MyTenant

This has been implemented for the --device, --tenant, --product, and --device-group parameters.

For example:

azsphere device-group update --device-group CoffeeMaker/Development
   ------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
   Id                                   TenantId                             OsFeedType ProductId                            Name      Description            UpdatePolicy                                               AllowCrashDumpsCollection
   ===============================================================================================================================================================================================================================================
   7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb Retail     6f52bead-700d-4289-bdc2-2f11f774270e Marketing Marketing device group Accept all updates from the Azure Sphere Security Service. False
   ------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------

Multiple values

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 spaces. For example, the following two commands are equivalent:

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

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

Required and optional parameters

When you run azsphere <command> <sub-command> --help a list of parameters applicable to that command is displayed. The [Required] setting indicates whether the parameter is mandatory to successfully run the command. All other parameters are optional.

If the required parameter is missing you are prompted for a value for the parameter.

For example:

azsphere role delete --help

Command
    azsphere role delete : Deletes a role from a user in the current Azure Sphere tenant.

Arguments
    --role -r [Required] : Role to be deleted. Values from: azsphere role show-types.
    --user -u [Required] : The user from whom the role is being deleted. Specify user e-mail.
                           Values from: azsphere role list.

Tenant Selection Arguments
    --tenant -t          : The tenant to perform this operation in. Overrides the default selected
                           tenant. Specify tenant ID or tenant name. Values from: azsphere tenant
                           list.

Global Arguments
    --debug              : Increase logging verbosity to show all debug logs.
    --help -h            : Show this help message and exit.
    --only-show-errors   : Only show errors, suppressing warnings.
    --output -o          : Output format. Allowed values: json, jsonc, none, table, tsv, yaml,
                           yamlc. Default: table.
    --query              : JMESPath query string. See http://jmespath.org/ for more information and
                           examples.
    --verbose            : Increase logging verbosity. Use --debug for full debug logs.

Input and output paths

In Azure Sphere CLI, the parameter names used to specify a path and file name has been updated to be relevant to the context of the command.

For example:

azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage

Here, --package-directory specifies the input directory for the package and --destination parameter specifies the path and filename for the resulting image package.

Tab completion

Tab completion provides help in automatically completing a command entry in the command-line interface. In the Azure Sphere CLI tab completion is supported for groups, commands, parameters names, and parameter values. Type a few characters of a command and then press TAB to select the desired completion text. If multiple items begin with the text that you initially typed, then continue pressing TAB until the item you want appears.

On Windows, PowerShell 7.1 offers the tab completion feature which is not available from the Windows Command Prompt.

To enable tab completion in Windows PowerShell, run Import-Module -name AzsphereCli. This command enables tab completion only for the session. You can add a script to your PowerShell profile to customize your environment and to enable tab completion for every PowerShell session that you start.

On Linux, Azure Sphere CLI supports the tab completion feature for commands under the Bash shell.

Additionally, autocompletion helps you discover commands, parameters, and parameter values that are available to use. This is available by using CTRL+Space in Windows PowerShell or press TAB twice in the Linux Bash shell.

For example, type azsphere product update command and use autocompletion to see a list of available parameters.

PowerShell autocompletion parameters

Similarly, type azsphere product update --product and use autocompletion to see a list of available products in your tenant.

PowerShell autocompletion products

Interactive mode (preview)

Important

This feature is in preview. It may be changed or removed in a future release.

The new CLI offers an interactive mode that automatically displays help information and makes it easier to select commands, sub-commands, parameter, and parameter values. Enter the interactive mode with the azsphere interactive command. The command prompt changes to azsphere>> to indicate that you are now running commands in the interactive shell. For more information, see Azure Sphere CLI interactive mode.

Azure Sphere interactive mode

CLI output features

This section explains of the output features available in the Azure Sphere CLI:

The following sections describes the output features available in the new CLI:

Supported output formats

The available output formats in the new CLI 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 Supported output formats for Azure Sphere CLI.

Redirection and pagination

Azure Sphere CLI does not support interactive pagination. You can, however, redirect the standard output of a command to a file. In the following example, for Windows Command Prompt, Windows PowerShell, and Linux Bash shell the standard output is sent to output.txt and standard error is sent to logs.txt.

azsphere device list --verbose > output.txt 2> logs.txt

You can also paginate the output on screen by piping to existing pagination tools.

For example:

  • In PowerShell (Windows): azsphere device list | Out-Host –Paging
  • At a command prompt (Windows): azsphere device list | more
  • In Bash shell (Linux): azsphere device list | less

Note

This operation can potentially be slow depending on how much data is returned.

For more information on pagination for Azure Azure Sphere classic CLI, see Paging and result redirection.

Query CLI command output

The Azure Sphere CLI uses the --query argument to run a JMESPath query on the results of commands. JMESPath is a query language for JSON, giving you the ability to select and modify data from CLI output. Queries are run on the JSON output before any display formatting.

The --query argument is supported by all commands in Azure Sphere CLI. See JMESPath tutorial and Query Azure CLI command output for more information and examples.

Backward compatibility

The CLI supports backward compatibility. In each release, we aim to maintain backwards compatibility for both input (command names, parameter names, parameter values) and its output in JSON and YAML. In cases where such compatibility is not possible, we will provide at least 6 months' notice before making changes. For more information, see Important changes (retiring features) in Azure Sphere CLI.

Exit codes

A successful command returns a zero. Any non-zero value can be interpreted as an error code. Upon success, the JSON and YAML outputs have a backward-compatible contractual guarantee.

Provide feedback

If you find a bug in Azure Sphere, file an issue on GitHub. To provide feedback from the command line, use the feedback command.

Use Azure Sphere CLI effectively

Azure Sphere CLI can be used from Bash, PowerShell, or a Command Prompt window. Here are a few tips for using the CLI:

  • Using quotation marks in values: If you provide a parameter a value that includes spaces, enclose it in quotation marks. In Bash or PowerShell, both single and double quotes are interpreted. In Windows Command Prompt, only double quotes are interpreted. Single quotes are interpreted as a part of the value. For example, azsphere product create --name "My Fridge Product". For more information, see Quotation marks and escapes characters.
  • Many Azure Sphere commands show you information in the console in the default table format. For example, azsphere product device-group list --product DW100. Sometimes the information displayed does not fit the console correctly. This can cause problems if you wish to copy and paste the information. We recommend trying the following options:
    • Resize the console and run the command again.
    • Use JSON output for concise output and scripting purposes. For example, azsphere product device-group list --product DW100 --output json.
    • Use tab-completion in Windows PowerShell or Bash shell to automatically complete a command entry.
    • Use the interactive mode which provides an interactive environment to automatically display information and makes it easier to select commands and sub-commands. Enter the interactive mode with the azsphere interactive command. The command prompt changes to azsphere>> to indicate that you are now running commands in the interactive shell.

See also