Quick Start¶

This walkthrough creates one configuration, validates it, and runs a command with the resolved variables.

Install dotenv-fusion first if needed:

uv tool install dotenv-fusion

Other installation methods are listed on the Installation page.

1. Create .env-fuse¶

ENV=${ENV:-development}
APP_NAME=my-application

#@def PORT type=int default=8000 min=1 max=65535 doc="HTTP listening port"
PORT=8000

#@if ${ENV} == production
LOG_LEVEL=warning
#@else
LOG_LEVEL=debug
#@endif

BASE_URL=http://localhost:${PORT}

The file remains readable as dotenv syntax. Directives start with #@, so tools that do not understand them still see comments.

2. Validate it¶

dotenv-fusion check

check validates directives, expansion, conditions, types, required values, and regular expressions without changing the shell or writing an output file.

3. Run a command¶

dotenv-fusion exec -- sh -c 'printf "%s on %s\n" "$APP_NAME" "$BASE_URL"'

The command receives:

my-application on http://localhost:8000

Select another environment with a build-time variable:

dotenv-fusion exec --var ENV=production -- application --serve

Choose the delivery method¶

Add capabilities when needed¶

• Organize imports and environment variants
• Separate a shared contract from local values
• Learn the directive syntax
• Resolve encrypted secrets with age
• Encrypt secrets from an existing .env