Azure Sphere CLI
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 --helporazsphere -? - For Azure Sphere CLI use,
azsphere --helporazsphere -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.
Similarly, type azsphere product update --product and use autocompletion to see a list of available products in your tenant.
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.
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
tableformat. 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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for