Getting Started

Prerequisites

Before installing azd exec, make sure you have:

• Azure Developer CLI (azd) installed on your system
• Azure subscription and appropriate permissions
• Basic knowledge of shell scripting (bash or PowerShell)

If you don't have azd installed, visit the official installation guide.

Install azd exec

Install the azd exec extension using the following commands for your platform:

# Install Azure Developer CLI
winget install microsoft.azd

# Enable extensions
azd config set alpha.extension.enabled on

# Add extension source
azd extension source add -n azd-exec -t url -l https://raw.githubusercontent.com/jongio/azd-exec/main/registry.json

# Install extension
azd extension install jongio.azd.exec

# Install Azure Developer CLI
brew tap azure/azd && brew install azd

# Enable extensions
azd config set alpha.extension.enabled on

# Add extension source
azd extension source add -n azd-exec -t url -l https://raw.githubusercontent.com/jongio/azd-exec/main/registry.json

# Install extension
azd extension install jongio.azd.exec

# Install Azure Developer CLI
curl -fsSL https://aka.ms/install-azd.sh | bash

# Enable extensions
azd config set alpha.extension.enabled on

# Add extension source
azd extension source add -n azd-exec -t url -l https://raw.githubusercontent.com/jongio/azd-exec/main/registry.json

# Install extension
azd extension install jongio.azd.exec

Verify Installation

Confirm that azd exec is installed correctly:

azd exec version

You should see output similar to:

azd exec version 0.1.0

Run Your First Script

Create a simple script to test azd exec:

For Bash/Linux/macOS

# Create a test script
cat > test-script.sh << 'EOF'
#!/bin/bash
echo "Azure Environment: $AZURE_ENV_NAME"
echo "Subscription: $AZURE_SUBSCRIPTION_ID"
echo "Location: $AZURE_LOCATION"
EOF

# Make it executable
chmod +x test-script.sh

# Review the script
cat test-script.sh

# Execute with azd exec
azd exec ./test-script.sh

For PowerShell/Windows

# Create a test script
@'
Write-Host "Azure Environment: $env:AZURE_ENV_NAME"
Write-Host "Subscription: $env:AZURE_SUBSCRIPTION_ID"
Write-Host "Location: $env:AZURE_LOCATION"
'@ | Out-File test-script.ps1

# Review the script
Get-Content test-script.ps1

# Execute with azd exec
azd exec ./test-script.ps1

Security Best Practices

Always Follow These Practices:

• ✅ Review scripts before running them
• ✅ Use HTTPS for any script downloads
• ✅ Verify the source of scripts from documentation or trusted repositories
• ✅ Store secrets in Azure Key Vault, not environment variables
• ❌ Never pipe untrusted scripts: curl http://site.com/script.sh | azd exec -
• ❌ Don't run scripts from unknown or untrusted sources

For comprehensive security information, see the Security Guidelines.

Common Commands

Basic Execution

azd exec ./my-script.sh

Pass Arguments

azd exec ./build.sh --verbose --config release

Specify Shell

azd exec --shell pwsh ./deploy.ps1

Set Working Directory

azd exec --cwd /path/to/project ./setup.sh

Interactive Mode

azd exec --interactive ./interactive-setup.sh

Azure Key Vault Integration

azd exec automatically resolves Azure Key Vault references in environment variables, allowing you to securely store and access secrets without hardcoding them.

Supported Reference Formats

Use any of these formats to reference Key Vault secrets:

# Format 1: SecretUri
@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/my-secret)
@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/my-secret/abc123)

# Format 2: VaultName and SecretName
@Microsoft.KeyVault(VaultName=myvault;SecretName=my-secret)
@Microsoft.KeyVault(VaultName=myvault;SecretName=my-secret;SecretVersion=abc123)

# Format 3: azd akvs URI (used internally by azd)
akvs://c3b3091e-400e-43a7-8ee5-e6e8cefdbebf/myvault/my-secret
akvs://c3b3091e-400e-43a7-8ee5-e6e8cefdbebf/myvault/my-secret/abc123

Quick Example

1. Store a secret in Azure Key Vault:

az keyvault secret set --vault-name myvault --name database-password --value "SuperSecret123!"

2. Set environment variable with Key Vault reference:

azd env set-secret DATABASE_PASSWORD

3. Use in your script:

#!/bin/bash
echo "Connecting to database..."
# DATABASE_PASSWORD is automatically resolved to the actual secret value
mysql -u admin -p"$DATABASE_PASSWORD" -h myserver.mysql.database.azure.com

4. Run the script:

azd exec ./deploy.sh

How It Works

• azd exec scans environment variables for Key Vault references
• Uses Azure DefaultAzureCredential (same authentication as azd)
• Fetches secret values from Key Vault before running your script
• Passes resolved values to your script securely
• If resolution fails, warns but continues with original values

Error Handling

By default, if Key Vault resolution fails (e.g., secret not found, no access), azd exec displays a warning but continues. To fail-fast on Key Vault errors, use the --stop-on-keyvault-error flag:

azd exec --stop-on-keyvault-error ./script.sh

For more examples, see the Key Vault examples section.

Next Steps