Share via

Migrate from classic CLI to 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.

If you are still using the Azure Sphere classic CLI, we recommend that you migrate to the new Azure Sphere CLI. Currently both versions of the CLI can be installed and used side by side, but the classic CLI is no longer updated or maintained and will be removed from SDK at a future date (not before the end of 2022). We encourage you to familiarize yourself with these differences and migrate your processes and scripts before the end of 2022 to avoid disruption.

To update to the latest SDK, see Install the Azure Sphere SDK on Linux or Install an Azure Sphere SDK for Windows.

To use Azure Sphere CLI on Windows, use PowerShell or a standard Windows Command Prompt. For Linux, use any command shell. For more information, see Run Azure Sphere CLI.

On Windows, the retiring custom Azure Sphere Classic Developer Command Prompt (available as a shortcut in the Start menu under Azure Sphere) can be used only with Azure Sphere classic CLI. For more information, see Run Azure Sphere classic CLI.

Key differences

  • In Azure Sphere classic CLI, multiple parameters can be used to identify each object type. In Azure Sphere CLI, a single parameter is used to identify each object type. This means you can use either the name or ID to specify the parameter value. This has been implemented for the --device, --tenant, --product, and --device-group parameters.

    Object type Azure Sphere CLI Azure Sphere classic CLI (retiring)
    Device --device --deviceid, --deviceip, or --devicelocation
    Device group --device-group --devicegroupid or --devicegroupname
    Product --product --productid or --productname
    Tenant --tenant --tenantid

  • Short form for commands is supported in the classic version. In Azure Sphere CLI, we recommend that you use the Tab completion or interactive feature to view the list of available commands. For example, in the classic CLI, you can use either azsphere device enable-development or azsphere dev edv command, whereas in the new Azure Sphere CLI you can use autocomplete to quickly type the azsphere device enable-development command.

  • 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

  • In the new CLI, the default tenant is not automatically selected when a tenant is created. You have to run the azsphere tenant select command to select the default tenant to use for the current user on the PC. This is to ensure that the default tenant is the correct one to use when performing a one-time operation that you cannot undo like claim the device.

    When using scripts, you can select the default tenant using the --tenant <tenant ID or tenant name> parameter.

    Set the default tenant at the start of the script using:

    azsphere tenant select --tenant <tenant ID or tenant name>

    You can also overwrite the default tenant or specify the required tenant when running the command. For example:

    azsphere get-support-data --destination logs.zip --tenant <tenant ID or tenant name>

  • The --device-group parameter identifies the device group. The device group ID supplies a GUID, which uniquely identifies the device group across all products. Alternatively, you can use the product name and device group name pair in the <product-name>/<device-group-name> format. This pair of names uniquely identifies a device group for a particular product.

  • The following commands were compound commands in the classic CLI. This means one command performed multiple tasks. In the new CLI you need to run the two commands.

    • In the classic CLI the azsphere device-group deployment create command uploaded the image package and created a new deployment.

      In the new CLI, you need to:

      1. Upload the image package to your Azure Sphere tenant by using azsphere image add.
      2. Create a new deployment for a device group for the uploaded images using azsphere device-group deployment create.

    • In the classic CLI the azsphere device capability download --select command downloaded and temporarily selected device capability configuration for the attached device.

      In the new CLI, you need to:

      1. Download the capability file by using azsphere device capability download.
      2. Select the capability by using azsphere device capability select.

    • In the classic CLI the azsphere device capability download --apply command downloaded and applied the device capability configuration for the attached device.

      In the new CLI, you need to:

      1. Download the capability file by using azsphere device capability download.
      2. Apply the capability by using azsphere device capability update.

  • In the classic CLI the -o or --output parameter is used to specify a path and file name at which to save a file. In the new Azure Sphere CLI, context-specific parameters are used such as --destination to specify input and output paths.

  • In the classic CLI the -d or --debug parameter is used in the azsphere device app start command to start the application in debug mode. In the new Azure Sphere CLI, the --debug-mode parameter is used to start the application in debug mode and the --debug parameter is used as a global parameter to increase logging verbosity to show all debug logs.

  • In the classic CLI there is no control over the output format. In Azure Sphere CLI, the -o or --output parameter is used to specify the output format in which to format the CLI output.

  • From release 21.02 onwards explicit version numbers have been removed from the Azure Sphere CLI product names. This change eliminates confusion in referring to the different versions of the product.

    • Azure Sphere CLI v2 and later are now referred to only as "Azure Sphere CLI".
    • Earlier Azure Sphere CLI versions (CLI v1 and lower) are now referred to as "Azure Sphere classic CLI".

  • If you are using scripts, they may not be compatible with the new Azure Sphere CLI due to the differences explained above. Make required updates for the scripts to run correctly in the new CLI.

See also