Add azd exec: run commands and scripts with azd environment context

[jongio]

Design Specification: design-spec.md

Problem

Running scripts that need azd environment variables today requires manual export/sourcing of .env files or wrapping commands in shell-specific workarounds. There's no first-class way to execute scripts or inline commands with full azd context (environment variables, Key Vault secret resolution) across platforms.

This also supersedes several long-standing env-loading requests: #391, #1697, #2336, #4067.

Related: #7423 proposes azd env exec as a core command ΓÇö see Open Discussion below.

Solution

Add the microsoft.azd.exec extension ΓÇö a cross-platform command and script execution engine that inherits azd environment context automatically.

Execution Modes

Invocation	Mode	How it works
azd exec python script.py	Direct exec	exec.Command("python", "script.py") ΓÇö exact argv, no shell
azd exec 'echo $VAR'	Shell inline	bash -c "echo $VAR" ΓÇö shell expansion available
azd exec ./setup.sh	Script file	bash ./setup.sh ΓÇö shell detected from extension
azd exec --shell pwsh "cmd"	Shell inline	pwsh -Command "cmd" ΓÇö explicit shell

Heuristic: Multiple arguments without --shell ΓåÆ direct process execution (OS exec semantics). Single quoted argument or explicit --shell ΓåÆ shell inline execution. File path ΓåÆ script file execution.

Features

• Direct process execution: Run programs with exact argv semantics (no shell wrapping) ΓÇö azd exec python script.py just works
• Script execution: Run script files or inline commands with configurable shell
• Environment loading: Inherits azd environment variables (Key Vault secret resolution handled by azd core)
• Cross-platform shells: bash, sh, zsh, pwsh, powershell, cmd
• Shell auto-detection: Detects shell from script file extension
• Exit code propagation: Child process exit codes forwarded faithfully for CI/CD pipelines
• Interactive mode: stdin passthrough for interactive scripts

Usage

# Install the extension
azd extension install microsoft.azd.exec

# Run a command directly with azd environment (exact argv, no shell wrapping)
azd exec python script.py
azd exec npm run dev
azd exec -- python app.py --port 8000 --reload
azd exec docker compose up --build

# Execute a script file ΓÇö shell auto-detected from file extension
azd exec ./setup.sh

# Inline shell command (single quoted argument uses shell)
azd exec 'echo $AZURE_ENV_NAME'

# Specify a shell explicitly
azd exec --shell pwsh "Write-Host $env:AZURE_STORAGE_ACCOUNT"

# Pass arguments through to the script
azd exec ./build.sh -- --verbose --output ./dist

# Interactive mode ΓÇö stdin passthrough for prompts
azd exec -i ./interactive-setup.sh

Architecture

main.go                    → Entry point with exit code propagation
internal/cmd/              → Cobra CLI commands (root, version, listen)
internal/executor/         → Script execution engine + command builder + error types
internal/shellutil/        → Shared shell detection and validation

3 focused internal packages, no circular dependencies, structured error types for programmatic handling.

Dependencies

• Depends on SDK features from feat(azdext): Extension SDK improvements — integration, security, runtime, cleanup #7025 and feat(azdext): Add KeyVault resolver for extension secret resolution #7043 (both merged)
• Uses pkg/azdext SDK for extension bootstrap and gRPC client

Open Discussion

Extension vs Core Command

This is implemented as an extension. Issue #7423 proposes a core azd env exec command. The extension approach provides faster iteration and no impact on core binary size, with the tradeoff of discoverability. Can be promoted to core later based on usage.

Key Vault Secret Auto-Resolution

The azd host resolves akvs:// and @Microsoft.KeyVault(...) references before passing environment to extensions. Child processes launched by azd exec receive materialized secrets. This is consistent with azd hooks behavior. weikanglim's feedback suggests this should be opt-in. If addressed, it should be at the host level (affecting all extensions/hooks).

Deliverables

• Extension source code (cli/azd/extensions/microsoft.azd.exec/)
• GitHub Actions lint workflow
• ADO release pipeline
• Cross-platform build scripts
• Direct process execution mode (exact argv semantics)
• Security hardening (control char stripping, debug log sanitization)
• Registry entry (added when first release publishes binaries with artifact checksums)

PR: #7400