Share via

az vm run-command

Manage run commands on a Virtual Machine.

For more information, see https://learn.microsoft.com/azure/virtual-machines/windows/run-command or https://learn.microsoft.com/azure/virtual-machines/linux/run-command.

Commands

Name Description Type Status
az vm run-command create

The operation to create the run command.

 Core GA
az vm run-command delete

The operation to delete the run command.

 Core GA
az vm run-command invoke

Execute a specific run command on a vm.

 Core GA
az vm run-command list

List run commands from a VM or a location.

 Core GA
az vm run-command show

Get specific run command.

 Core GA
az vm run-command update

The operation to update the run command.

 Core GA
az vm run-command wait

Place the CLI in a waiting state until a condition of the res virtual-machine-run-command is met.

 Core GA

az vm run-command create

Edit

The operation to create the run command.

az vm run-command create --name --run-command-name
                         --resource-group
                         --vm-name
                         [--async-execution {false, true}]
                         [--command-id]
                         [--error-blob-uri]
                         [--location]
                         [--no-wait]
                         [--output-blob-uri]
                         [--parameters]
                         [--protected-parameters]
                         [--run-as-password]
                         [--run-as-user]
                         [--script]
                         [--script-uri]
                         [--tags]
                         [--timeout-in-seconds]

Examples

Create a run command.

az vm run-command create --resource-group "myResourceGroup" --location "West US" --async-execution false --parameters arg1=param1 arg2=value1 --run-as-password "<runAsPassword>" --run-as-user "user1" --script "Write-Host Hello World!" --timeout-in-seconds 3600 --run-command-name "myRunCommand" --vm-name "myVM"

Create a run command with uploading script output stream to Azure storage blob (SAS URI).

az vm run-command create --resource-group "myResourceGroup" --location "West US" --script "Write-Host Hello World!" --run-command-name "myRunCommand" --vm-name "myVM" --output-blob-uri "https://mystorageaccount.blob.core.windows.net/mycontainer/RuncommandOutput.txt?sp=racw&st=2022-10-17T19:02:15Z&se=2022-10-18T03:02:15Z&spr=https&sv=2021-06-08&sr=b&sig=3BxtEasfdasdfasdfdYki9yvYsqc60V0%3D"

Required Parameters

--name --run-command-name

The name of the virtual machine run command.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--vm-name

The name of the virtual machine.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--async-execution

Optional. If set to true, provisioning will complete as soon as the script starts and will not wait for script to complete.

Property Value
Accepted values: false, true
--command-id

Specify a commandId of predefined built-in script.

--error-blob-uri

Specify the Azure storage blob where script error stream will be uploaded.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--output-blob-uri

Specify the Azure storage blob (SAS URI) where script output stream will be uploaded.

--parameters

The parameters used by the script.

Usage: --parameters arg1=XX arg2=XX.

--protected-parameters

The parameters used by the script.

Usage: --protected-parameters credentials=somefoo secret=somebar.

--run-as-password

Password if needed for using run-as-user parameter. It will be encrypted and not logged.

--run-as-user

By default script process runs under system/root user. Specify custom user to host the process.

--script

Specify the script content to be executed on the VM.

--script-uri

Specify the script download location.

--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--timeout-in-seconds

The timeout in seconds to execute the run command.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az vm run-command delete

Edit

The operation to delete the run command.

az vm run-command delete --name --run-command-name
                         [--ids]
                         [--no-wait]
                         [--resource-group]
                         [--subscription]
                         [--vm-name]
                         [--yes]

Examples

Delete a run command.

az vm run-command delete --resource-group "myResourceGroup" --run-command-name "myRunCommand" --vm-name "myVM"

Required Parameters

--name --run-command-name

The name of the virtual machine run command.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

Property Value
Parameter group: Resource Id Arguments
--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property Value
Parameter group: Resource Id Arguments
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property Value
Parameter group: Resource Id Arguments
--vm-name

The name of the virtual machine.

Property Value
Parameter group: Resource Id Arguments
--yes -y

Do not prompt for confirmation.

Property Value
Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az vm run-command invoke

Edit

Execute a specific run command on a vm.

az vm run-command show returns helpful information on each run-command. Discover Run command-id's via az vmss run-command list.

az vm run-command invoke --command-id
                         [--ids]
                         [--name]
                         [--no-wait]
                         [--parameters]
                         [--resource-group]
                         [--scripts]
                         [--subscription]

Examples

Install nginx on a linux VM.

az vm run-command invoke -g MyResourceGroup -n MyVm --command-id RunShellScript --scripts "sudo apt-get update && sudo apt-get install -y nginx"

Run shell command on a linux VM with parameters.

az vm run-command invoke -g MyResourceGroup -n MyVm --command-id RunShellScript --scripts 'echo $1 $2' --parameters hello world

Run powershell script on a windows VM with parameters. Script supplied inline. Be wary of single-quoting in CMD.exe.

az vm run-command invoke  --command-id RunPowerShellScript --name win-vm -g my-resource-group  \
    --scripts 'param([string]$arg1,[string]$arg2)' \
    'Write-Host This is a sample script with parameters $arg1 and $arg2' \
    --parameters 'arg1=somefoo' 'arg2=somebar'

Run powershell script on a windows VM with parameters. Script supplied from file.

# script.ps1
#   param(
#       [string]$arg1,
#       [string]$arg2
#   )
#   Write-Host This is a sample script with parameters $arg1 and $arg2

az vm run-command invoke  --command-id RunPowerShellScript --name win-vm -g my-resource-group \
    --scripts @script.ps1 --parameters "arg1=somefoo" "arg2=somebar"

Required Parameters

--command-id

The command id.

Property Value
Value from: az vm run-command list

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

Property Value
Parameter group: Resource Id Arguments
--name -n

The name of the Virtual Machine. You can configure the default using az configure --defaults vm=<name>.

Property Value
Parameter group: Resource Id Arguments
--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--parameters

Space-separated parameters in the format of '[name=]value'.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property Value
Parameter group: Resource Id Arguments
--scripts

Space-separated script lines. Use @{file} to load script from a file.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property Value
Parameter group: Resource Id Arguments
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az vm run-command list

Edit

List run commands from a VM or a location.

You can specify "--resource-group" and "--vm-name" to get all run commands of a virtual machine. Or you can specify "--location" to list all available run commands for a subscription in a location.

az vm run-command list [--expand]
                       [--location]
                       [--resource-group]
                       [--vm-name]

Examples

List run commands in a virtual machine.

az vm run-command list --resource-group "myResourceGroup" --vm-name "myVM"

List all available run commands for a subscription in a location.

az vm run-command list --location "SoutheastAsia"

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--expand

The expand expression to apply on the operation.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--vm-name

The name of the virtual machine.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az vm run-command show

Edit

Get specific run command.

You can specify "--resource-group", "--run-command-name" and "--vm-name" to get run command in a virtual machine. Or you can specify "--command-id" and "--location" to get run command for a subscription in a location.

az vm run-command show [--command-id]
                       [--ids]
                       [--instance-view]
                       [--location]
                       [--name --run-command-name]
                       [--resource-group]
                       [--subscription]
                       [--vm-name]

Examples

Get the run commands in a virtual machine.

az vm run-command show --resource-group "myResourceGroup" --run-command-name "myRunCommand" --vm-name "myVM"

Get specific run command for a subscription in a location.

az vm run-command show --command-id "RunPowerShellScript" --location "SoutheastAsia"

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--command-id

The command id.

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

Property Value
Parameter group: Resource Id Arguments
--instance-view

The instance view of a run command.

Property Value
Default value: False
--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--name --run-command-name

The name of the virtual machine run command.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property Value
Parameter group: Resource Id Arguments
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property Value
Parameter group: Resource Id Arguments
--vm-name

The name of the virtual machine.

Property Value
Parameter group: Resource Id Arguments
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az vm run-command update

Edit

The operation to update the run command.

az vm run-command update --name --run-command-name
                         [--async-execution {false, true}]
                         [--command-id]
                         [--error-blob-uri]
                         [--ids]
                         [--location]
                         [--no-wait]
                         [--output-blob-uri]
                         [--parameters]
                         [--protected-parameters]
                         [--resource-group]
                         [--run-as-password]
                         [--run-as-user]
                         [--script]
                         [--script-uri]
                         [--subscription]
                         [--tags]
                         [--timeout-in-seconds]
                         [--vm-name]

Examples

Update a run command.

az vm run-command update --resource-group "myResourceGroup" --location "West US" --async-execution false --parameters arg1=param1 arg2=value1 --run-as-password "<runAsPassword>" --run-as-user "user1" --script "Write-Host Hello World!" --timeout-in-seconds 3600 --run-command-name "myRunCommand" --vm-name "myVM"

Update a run command with uploading script output stream to Azure storage blob (SAS URI).

az vm run-command update --resource-group "myResourceGroup" --location "West US" --script "Write-Host Hello World!" --run-command-name "myRunCommand" --vm-name "myVM" --output-blob-uri "https://mystorageaccount.blob.core.windows.net/mycontainer/RuncommandOutput.txt?sp=racw&st=2022-10-17T19:02:15Z&se=2022-10-18T03:02:15Z&spr=https&sv=2021-06-08&sr=b&sig=3BxtEasfdasdfasdfdYki9yvYsqc60V0%3D"

Required Parameters

--name --run-command-name

The name of the virtual machine run command.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--async-execution

Optional. If set to true, provisioning will complete as soon as the script starts and will not wait for script to complete.

Property Value
Accepted values: false, true
--command-id

Specify a commandId of predefined built-in script.

--error-blob-uri

Specify the Azure storage blob where script error stream will be uploaded.

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

Property Value
Parameter group: Resource Id Arguments
--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--output-blob-uri

Specify the Azure storage blob (SAS URI) where script output stream will be uploaded.

--parameters

The parameters used by the script.

Usage: --parameters arg1=XX arg2=XX.

--protected-parameters

The parameters used by the script.

Usage: --protected-parameters credentials=somefoo secret=somebar.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property Value
Parameter group: Resource Id Arguments
--run-as-password

Password if needed for using run-as-user parameter. It will be encrypted and not logged.

--run-as-user

By default script process runs under system/root user. Specify custom user to host the process.

--script

Specify the script content to be executed on the VM.

--script-uri

Specify the script download location.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property Value
Parameter group: Resource Id Arguments
--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--timeout-in-seconds

The timeout in seconds to execute the run command.

--vm-name

The name of the virtual machine.

Property Value
Parameter group: Resource Id Arguments
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az vm run-command wait

Edit

Place the CLI in a waiting state until a condition of the res virtual-machine-run-command is met.

az vm run-command wait [--command-id]
                       [--created]
                       [--custom]
                       [--deleted]
                       [--exists]
                       [--ids]
                       [--instance-view]
                       [--interval]
                       [--location]
                       [--name --run-command-name]
                       [--resource-group]
                       [--subscription]
                       [--timeout]
                       [--updated]
                       [--vm-name]

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--command-id

The command id.

--created

Wait until created with 'provisioningState' at 'Succeeded'.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--custom

Wait until the condition satisfies a custom JMESPath query. E.g. provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running'].

Property Value
Parameter group: Wait Condition Arguments
--deleted

Wait until deleted.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--exists

Wait until the resource exists.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

Property Value
Parameter group: Resource Id Arguments
--instance-view

The instance view of a run command.

Property Value
Default value: False
--interval

Polling interval in seconds.

Property Value
Parameter group: Wait Condition Arguments
Default value: 30
--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--name --run-command-name

The name of the virtual machine run command.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Property Value
Parameter group: Resource Id Arguments
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

Property Value
Parameter group: Resource Id Arguments
--timeout

Maximum wait in seconds.

Property Value
Parameter group: Wait Condition Arguments
Default value: 3600
--updated

Wait until updated with provisioningState at 'Succeeded'.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--vm-name

The name of the virtual machine.

Property Value
Parameter group: Resource Id Arguments
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False