Add a first-class command to run a process with the current azd environment loaded

[weikanglim]

Summary

Issue #4384 highlights a recurring problem: users need a safe, standard way to run local scripts and applications with azd environment values available, without leaking those values into the parent shell or relying on language-specific loaders.

This issue proposes a first-class azd command to run an arbitrary child process with the selected azd environment loaded into that process only.

This is proposed as an alternative to PR #7364, which adds --export to azd env get-values for shell sourcing. Instead of making shell export the primary mechanism, this proposal focuses on direct process execution for scripting scenarios that already have wide usage today.

Working name:

azd env exec <command> [args...]

Examples:

azd env exec python script.py
azd env exec uv run app.py
azd env exec npm run dev
azd env exec -e myenv ./write-env.sh
# for passing flags to the script, `--` is required
azd env exec -- python script.py --port 8000 --reload
azd env exec -e myenv -- docker compose up --build

This issue is about the behavior and user experience, not the final command name. The basic form should be azd env exec python script.py, and the command should also support -- so users can cleanly pass flags through to the child process when needed.

What

We should add a command that:

• Resolves the current azd environment, or a specific one via --environment
• Loads azd environment values into a child process
• Runs the requested command directly, preserving stdin, stdout, and stderr
• Returns the child process exit code
• Does not mutate the caller's shell or parent process environment

At a high level, this should let users and tools say "run this program with the active azd environment" without having to manually export variables, source shell fragments, or write language-specific environment loaders.

Why

Today, users typically have to choose between a few imperfect options:

1. Put the command behind a hook and run it via azd or azd hooks run
2. Export azd variables into the current shell
3. Load the azd .env file inside the app with language-specific code

Each workaround has drawbacks:

• Hooks are useful, but they require command definitions in azure.yaml and make azd the entry point for running the app or script
• Exporting values into the current shell is shell-specific, easy to misuse, and can leave behind stale variables that taint later commands
• Language-specific loaders create extra per-language guidance and complexity for templates and samples

This directly addresses the underlying issue described in #4384 by giving users a standard, shell-agnostic way to run scripts with azd env loaded, while avoiding the parent-shell tainting and export-driven confusion called out in that issue.

There is also a tooling and automation benefit here: azd env exec python script.py is much easier for agents, scripts, and task runners to invoke safely than a pattern based on eval, source, or shell-generated export output.

Scoping

In scope for this issue:

• Running an explicit command with azd env loaded
• Supporting --environment
• Child-process-only environment behavior
• Exit code passthrough
• Interactive command support when the child process needs a TTY

Out of scope for this issue:

• Auto-exporting to .env files
• Merging or syncing variables into app-specific config files
• Persisting env vars in the user's current shell
• A full azd SDK/library story for each language
• Secret-resolution enhancements beyond whatever the current azd environment-loading model already supports
• A more targeted service-simulation experience for running an azd service locally

Open questions

• Should this live under azd env exec, azd shell, or another name?
• Should the initial issue only support explicit commands, or also support "no args" interactive shell launching later?
• Do we want to support any extra filtering or service-scoped behavior now, or keep v1 strictly to "selected azd env as-is"?

Future direction

Longer term, we may want a higher-level command such as azd run that provides a more targeted development experience, potentially simulating how a service runs within azd and layering in service-specific behavior.

That should be treated as a future direction, not a prerequisite for this issue.

This issue is intentionally focused on the lower-level scripting capability that has broad usage today: run an arbitrary command with azd env loaded.

Why this is worth doing first

This is the smallest first-class feature that closes the biggest gap:

• it avoids shell tainting
• it works well for local dev and automation
• it aligns with existing hook behavior
• it gives templates and docs a much cleaner recommendation than export-based workarounds
• it provides a clearer answer to the core ask in A standard or better way to populate local environments with azd env variables #4384 than asking users to eval generated shell exports

If we later add a separate export/sync feature, the two can complement each other:

• env exec for "run a process safely"
• env export / sync for "write selected values to a file"

[weikanglim]

Proposed high-level changes

1. Add a dedicated run-with-env command

Introduce a command with behavior equivalent to:

• resolve azd environment
• build the process environment for the child command
• launch the child command directly
• stream I/O through to the console
• return the child exit code

Initial scope should focus on explicit command execution:

azd env exec <command> [args...]

2. Reuse existing azd environment-loading behavior

We already load azd environment values for hooks. The new command should reuse the same environment resolution model where practical instead of inventing a separate code path.

That likely means extracting or reusing the logic that:

• finds the selected environment
• gathers the azd .env values
• prepares process environment variables for child execution

3. Keep the command shell-agnostic

The command should execute a child process directly instead of producing shell snippets that the caller must eval or source.

That keeps the feature:

• cross-shell
• easier to document
• safer for automation
• less prone to quoting and escaping issues

4. Make non-goals explicit

This command should not:

• export values into the caller's shell
• replace a future dedicated export/file-sync workflow
• require the command to be defined in azure.yaml

Those are separate scenarios and should stay separate.

[weikanglim]

@jongio curious for your take and learnings here, especially relative to #7400. These seem to agree on the underlying need, but diverge on a few important design choices that I would appreciate your weigh-in:

1. Core vs extension — should this live in core as an azd env exec-style primitive, or is an extension the right place to iterate first?
2. Process vs shell model — should the primary experience be “run a child process with azd env injected” (azd env exec python script.py), or a more shell/script-oriented model (azd exec ./script.sh, inline commands, shell detection)?
3. Secret handling — should secret / Key Vault resolution happen automatically as part of env loading, or should materializing secrets require an explicit flag / opt-in?
4. Scenario gap — what concrete scenarios are you optimizing for with azd exec that are not already solved by the narrower azd env exec <command> [args...] design proposed here?

[jongio]

Great issue — we're aligned on the underlying need. PR #7400 (microsoft.azd.exec) is the implementation of exactly this. Let me answer each question directly:

1. Core vs extension — should this live in core as an azd env exec-style primitive, or is an extension the right place to iterate first?

Extension. This follows the extension-first architecture the team has established. It lets us iterate on the UX without gating on core release cycles. The extension framework already handles environment loading — azd core injects the active environment's values (including resolved Key Vault secrets) into extension processes automatically (cmd/extensions.go:221-234). The extension just uses os.Environ() and focuses on execution logic. If this proves fundamental enough to graduate to core later, the extension is a self-contained directory — easy to migrate.

2. Process vs shell model — should the primary experience be "run a child process with azd env injected" (azd env exec python script.py), or a more shell/script-oriented model (azd exec ./script.sh, inline commands, shell detection)?

Both are supported. azd exec python script.py works as direct process execution. azd exec ./setup.sh auto-detects the shell from the file extension. azd exec --shell pwsh "Write-Host $env:FOO" runs inline commands with an explicit shell. The shell model is additive — you get the simple exec <command> [args...] case by default, and shell features when you need them.

3. Secret handling — should secret / Key Vault resolution happen automatically as part of env loading, or should materializing secrets require an explicit flag / opt-in?

Automatic. azd core already resolves Key Vault secret references (keyvault:// URIs) for all extensions before they launch. The extension doesn't need to do anything — secrets are already materialized in the process environment. This matches what hooks do today. No opt-in needed, no separate code path.

Note: there's a known issue with env value munging during the azd env get-values dotenv serialization roundtrip (leading zeros stripped, quoting edge cases). PR #7314 fixes this at the core level, which will simplify the extension's env loading path and resolve the issue for all consumers.

4. Scenario gap — what concrete scenarios are you optimizing for with azd exec that are not already solved by the narrower azd env exec <command> [args...] design proposed here?

The main additions beyond the base exec <command> case:

• Shell auto-detection: azd exec ./setup.ps1 picks PowerShell, azd exec ./init.sh picks bash — no --shell required. Cross-platform templates can ship scripts and the right shell is selected automatically.
• Inline commands: azd exec 'echo $AZURE_ENV_NAME' for quick one-liners without creating a script file.
• Interactive mode: -i flag for scripts that need stdin (prompts, confirmations).
• Exit code propagation: Child process exit codes forwarded faithfully for CI/CD pipeline integration.

These are the patterns we see in templates and automation today that eval $(azd env get-values) handles poorly.

See PR #7400 for the full implementation — 500 lines of prod code, 90%+ test coverage, follows extension conventions.

[weikanglim]

Thanks for the detailed reply — I agree we’re aligned on the underlying need, but I still see a few important differences in direction.

On core vs extension, I have some general discoverability concerns with putting this behind an extension. This has also been requested as core functionality, and I don’t think we necessarily give up iteration speed by putting it in core if we mark it clearly as an alpha/beta command while we learn from usage.

On process vs shell semantics, I think this distinction matters more than it may seem. If the goal is exec <command> [args...], users will reasonably expect OS/process semantics: preserve argv exactly, launch the requested program directly, and behave consistently across platforms. The current default-shell fallback changes that model.

For example, a user naturally expects:

azd exec -- python myapp.py --port 8000

to run python with myapp.py --port 8000. But with default-shell behavior, that can become shell-mediated execution instead, where the extra tokens are treated as shell positional parameters rather than Python arguments. On Unix, that pushes users toward something much more shell-specific like:

azd exec 'python "$@"' -- myapp.py --port 8000

That feels like a meaningful change in contract: the command stops being “run this process with azd env” and becomes “run this shell snippet with azd env.”

Related to that, defaulting to bash when no shell is specified also feels limiting in environments where only sh is available. That default pulls in a stronger shell assumption than a process-level exec primitive needs.

On secret handling, I’m uneasy with automatic secret resolution as the default. Materializing secrets into the environment feels like something the user should opt into explicitly, rather than have happen implicitly as part of command execution. From a UX and security perspective, I think an explicit flag is a clearer boundary and more in line with how other IaC/dev tools tend to treat secret materialization (for example, Pulumi).

More broadly, I worry we may be over-optimizing for shell-script scenarios when the simpler and more common need is just: “run my language/tool command with the azd environment loaded” — Python, Node, uv, npm, docker compose, etc.

To me, these feel like two related but distinct commands:

• OS-exec-driven: run a program with exact argv semantics and azd env injected
• Shell-driven: run a shell/script experience with shell parsing, shell expansion, inline commands, and shell-specific behavior

If the direction being advocated is primarily shell-driven execution, that sounds closer to an azd shell concept to me than a narrow azd env exec primitive.

For an end user, the distinction is meaningful because it changes whether arguments are passed to the target program exactly as written, whether behavior is cross-platform consistent, whether quoting/escaping rules are shell rules or process rules, whether secrets are injected implicitly or only on explicit request, and whether the mental model is “run my app/tool” or “run this shell expression.”