az vm run-command: Run Commands on a VM

az vm run-command invoke runs a script inside a VM through the agent, with no SSH or open port.

When a pipeline must configure a VM but you do not want to manage SSH keys or open 22, run-command sends the script over the Azure control plane.

What it does

az vm run-command invoke executes a built-in command (such as RunShellScript on Linux or RunPowerShellScript on Windows) inside the VM via its guest agent, returning stdout and stderr in the response. No inbound network access is required.

Common usage

Terminal

az vm run-command invoke \
  --resource-group rg-app --name vm-runner \
  --command-id RunShellScript \
  --scripts "sudo systemctl restart myapp"
# capture just the script stdout
az vm run-command invoke -g rg-app -n vm-runner \
  --command-id RunShellScript --scripts "uname -a" \
  --query "value[0].message" -o tsv

Subcommands and flags

Flag	What it does
invoke	Run a command and wait for the result
--command-id	RunShellScript or RunPowerShellScript
--scripts	Inline script lines to execute
--parameters	Named arguments passed to the script
--query "value[0].message"	Extract the combined output

In CI

run-command is ideal for runners on private VMs: no port 22, no key handling. The output nests under value[0].message, so use --query to pull it out. Keep scripts short; the call has a timeout and is not a substitute for a full provisioning tool.

Common errors in CI

"ResourceNotFound" means the VM name or group is wrong. "VMAgentStatusCommunicationError" or a hang means the guest agent is not running or the VM is stopped. "AuthorizationFailed" means the identity lacks the runCommand action; Virtual Machine Contributor covers it.