Pass arguments and environment¶

Give the debugged program the command line and the environment it expects.

Arguments¶

[profiles.app]
adapter = "dlv"
program = "cmd/api"
args = ["--config", "${root}/configs/dev.yaml", "--verbose"]

One list element per argument. A value containing a space is still one element:

args = ["--message", "hello world"]        # two arguments — correct
args = ["--message hello world"]           # one argument — almost certainly wrong

There is no shell: no word splitting, no globbing, no $VAR expansion. The only substitution is ${root}, which becomes the absolute project root.

Environment: two fields for two purposes¶

[profiles.api]
adapter = "dlv"
program = "cmd/api"
env_file = ".env"
env = { LOG_LEVEL = "debug", ROOT = "${root}" }

env_file — shared with the team, lives in the repository or in .gitignore.
env — the targeted edit for right now.

Precedence, weakest to strongest: inherited environment → env_file → env.

What the profile states explicitly always wins, so a stale DATABASE_URL in your shell cannot quietly beat the config.

Recipes¶

The app reads `.env` itself¶

Nothing to do — the working directory is the project root, so a relative .env is found the same way it is when you run the program by hand.

The app does not read `.env` itself¶

If the variables used to arrive from direnv or an editor extension, name the file:

env_file = ".env"

A monorepo with a shared `.env` above the root¶

# services/api/.bugsaur/config.toml
[profiles.api]
adapter = "dlv"
program = "."
env_file = "../../.env"

A different `.env` per command¶

[profiles.worker]
adapter = "dlv"
program = "cmd/worker"
env_file = "cmd/worker/.env"

Turning on debug logging for one run¶

env = { LOG_LEVEL = "debug", RUST_LOG = "trace" }

Variables `cargo run` sets that a direct launch does not¶

env = { CARGO_MANIFEST_DIR = "${root}" }

The `.env` format¶

# a comment
DATABASE_URL=postgres://localhost/app
export PORT=8080
GREETING="hello  world"     # quotes preserve spaces
MULTI="a\nb"                # inside double quotes: \n \r \t \\ \"
LITERAL='a\nb'              # inside single quotes the value is literal
HASH=a#b                    # a comment only starts at ` #`
EMPTY=

No ${VAR} interpolation, no multi-line values. A line that does not parse stops the launch and names its number. With a repeated key, the last one wins.

PHP takes neither¶

The PHP adapter launches nothing, so args, env and env_file do not apply. Pass them where PHP actually starts — docker-compose.yml, the FPM pool config, or the command line:

APP_ENV=dev php src/import.php --dry-run

When it does not work¶

Symptom	Cause	Fix
Launch stops: `env_file` not found	the file was named but does not exist	fix the path — it is relative to the root
Launch stops on a `.env` line	that line does not parse	check quoting; no interpolation is supported
A variable has the wrong value	something stronger overrode it	`env` beats `env_file` beats the inherited environment
`${VAR}` appears literally in a value	`.env` does not interpolate	write the value out, or set it in `env`
An argument arrives as one string	it was written as one list element	split it into separate elements

Pass arguments and environment¶

Arguments¶

Environment: two fields for two purposes¶

Recipes¶

The app reads .env itself¶

The app does not read .env itself¶

A monorepo with a shared .env above the root¶

A different .env per command¶