How to use shorthand syntax with Azure CLI

Many Azure CLI parameters accept JSON values, but because it can be challenging to flatten JSON into a string, the Azure CLI supports shorthand syntax. Shorthand syntax is a simplified representation of a JSON string.

This article provides examples of shorthand syntax, and shows how to pass JSON as a file.

Full value shorthand syntax

Shorthand syntax in Full Value format is JSON surrounded by double quotes. Double quotes cause the JSON value to be passed as a string in both the PowerShell and Bash scripting language. Here's a JSON example:

{
  "name": "Bill",
  "age": 20,
  "paid": true,
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "address": {
    "country": "USA",
    "company": "Microsoft",
    "details": {
      "line1": "15590 NE 31st St",
      "line2": "Redmond, WA"
    }
  }
}

When you pass JSON in a parameter value, the JSON is flattened and wrapped in double quotes.

az some-command --contact "{name:Bill,age:20,paid:true,emails:[[email protected],[email protected]],address:{country:USA,company:Microsoft,details:{line1:'15590 NE 31st St',line2:'Redmond, WA'}}}"

Partial value shorthand syntax

Shorthand syntax for partial value is composed of two parts joined by an equal (=) sign between the index key and the value. Here's an example: key=value.

The value can be a simplified string, full value format, JSON, or a JSON file path. Using the JSON example provided, pass properties for the --contact parameter following these examples:

Use Partial Value for a single key-value pair.

az some-command --contact name=Bill

Use Partial Value for two key-value pairs. Note the space that separates the two pairs.

az some-command --contact age=20 paid=true

Use Partial Value for second element.

az some-command --contact emails[1]="[email protected]"

Use Partial Value for details property of address.

az some-command --contact address.details="{line1:'15590 NE 31st St',line2:'Redmond, WA'}"

Combine full and partial value shorthand syntax

You can combine full and partial value syntax, but always start with Full Value followed by Partial Value. If you reverse the order, the final data only contains the Full Value without properties defined in Partial Value.

Use Full Value followed by Partial Value:

az some-command --contact "{name:Bill,age:20,paid:true,emails:[[email protected],[email protected]]}" motto="One man's bug is another man's lesson."

You can also patch a new element of list property in Full Value. For example you can set the second email address by Partial Value:

az some-command --contact "{name:Bill,age:20,paid:true,emails:[[email protected]]}" emails[1]="[email protected]" motto="One man's bug is another man's lesson."

Pass JSON in a file

It's also possible to pass a JSON file as a parameter value. This is the recommended approach when working with complex JSON.

az some-command --contact address.details=./address_details.JSON

Single Quotes String

Single Quotes String is used to pass a string value with special characters: :, ,, {, }, [, ], null, ??, and space. These characters often have other meanings when parsing shorthand syntax. Single quotes tell the parser to treat everything as a string.

Pass a string value with a space and other special characters

Here's example JSON to pass as a value in the --contact parameter:

{
  "name": "Bill RP",
  "age": 20,
  "paid": true,
  "data": "{a: [1, 2]}"
}

Use single quotes in Full Value format:

az some-command --contact "{name:'Bill RP',age:20,paid:true,data:'{a: [1, 2]}'}"

Use single quotes in Partial Value format:

az some-command --contact name="'Bill RP'" data="'{a: [1, 2]}'"

In the next example, it's also possible to remove single quotes for the name key. The parser doesn't distinguish between a Full Value expression, null value, or the ?? flag.

Use Partial Value format:

az some-command --contact name="Bill RP"

Work with apostrophes

The apostrophe character (') needs special escape (/') in Single Quotes String in order to distinguish the end of a Single Quotes String. A forward slash (/) is an escape character only after an apostrophe (') in Single Quotes String. If / isn't in Single Quotes String or / isn't after ', / is a normal character.

Pass Full Value format:

az some-command --contact "{name:'bill'/s',age:20,paid:true}"

Pass Partial Value format:

az some-command --contact name="'bill'/s'"

If value isn't in Single Quotes String, you don't need to add an escape character after '.

Pass Partial Value format:

az some-command --contact name="bill's"

Here's another example using the following JSON:

{
  "name": "Bill",
  "motto": "One man's bug is another man's lesson.",
  "age": 20,
  "paid": true,
  "emails": [
    "[email protected]",
    "[email protected]"
  ]
}

In Full Value format, use a Single Quotes String and replace the ' with '/.

az some-command --contact "{name:Bill,motto:'One man'/s bug is another man'/s lesson.',age:20,paid:true,emails:[[email protected],[email protected]]}"

In Partial Value format, a value containing an apostrophe can be parsed as string, surrounded by double quotes.

az some-command --contact motto="One man's bug is another man's lesson."

Work with NULL values

Pass the word "null" as a string value

Sometime you need to pass a "null" string value. In order to distinguish with null value, it needs to be a Single Quotes String. For example if you want to pass "null" string into the name property in the --contact parameter:

JSON:

{
  "name": "null",
  "age": 20,
  "paid": true
}

Use Full Value format:

az some-command --contact "{name:'null',age:20,paid:true}"

Use Partial Value format:

az some-command --contact name="'null'"

Pass a null value

Shorthand syntax support null keyword in both Full Value and Partial Value formats.

For example if you want to pass following object with a null value address property in the --contact parameter:

{
  "name": "Bill",
  "age": 20,
  "paid": true,
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "address": null
}

Use Full Value format:

az some-command --contact "{name:Bill,age:20,paid:true,emails:[[email protected],[email protected]],address:null}"

Use Partial Value format:

az some-command --contact name=Bill address=null

Use a null value in update commands

In update commands, a null value is often used to unset properties of an object, or remove elements of an array or a dictionary.

{
  "contact": {
    "name": "Bill",
    "age": 20,
    "paid": true,
    "emails": [
      "[email protected]",
      "[email protected]"
    ],
    "address": {
      "country": "USA",
      "company": "Microsoft",
      "details": {
        "line1": "15590 NE 31st St",
        "line2": "Redmond, WA"
      }
    }
  },

  "other_properties": {}
}

If there already exists a resource with the JSON values shown above, passing a null value in an update command resets the key's value.

az some-update-command --contact address=null

Here's another example that removes the first element of a resource's email:

az some-update-command --emails [0]=null

Use ?? to show help

The use of double question marks ?? is a special keyword to show the available help for a parameter or subproperty. It can also be used within shorthand syntax to get help.

Use ?? to show a parameter's help message

Show help message of --contact parameter:

az some-command --contact "??"

Use ?? in Full Value format

Show help message of --contant parameter when writing Full Value:

az some-command --contact "{??"

az some-command --contact "{name:Bill,??"

Show help message of --contant.address property when writing Full Value:

az some-command --contact "{name:Bill,address:??"

Show help message of --contant.address.country property when writing Full Value:

az some-command --contact "{name:Bill,address:{country:??"

Show help message of --contant.emails property when writing Full Value:

az some-command --contact "{name:Bill,address:{country:USA},emails:??"

Show help message of the element of --contant.emails property when writing Full Value:

az some-command --contact "{name:Bill,address:{country:USA},emails:[??"

Use ?? in Partial Value format

Show help message of --contant.address property when writing Partial Value:

az some-command --contact address="??"

Show help message of --contant.emails property when writing Partial Value:

az some-command --contact emails="??"

Show help message of the element of --contant.emails property when writing Partial Value:

az some-command --contact emails[0]="??"

See also

• Quoting differences between scripting languages - JSON strings