Skip to content

Roadmap

This roadmap describes product direction, not release commitments. Interfaces shown below are proposals until they appear in the CLI reference.

Current baseline

dotenv-fusion already provides the foundation on which future work should build:

  • a readable .env-fuse configuration graph with imports, conditions, types, validation, documentation, and deterministic precedence;
  • check, load, and exec for validation, shell integration, and direct application startup;
  • fuse for explicit plaintext artifacts, including dry-run and redacted drift review;
  • age-encrypted secret bundles through source="age://...", with safe editing and migration from an existing .env;
  • reusable .env-schema contracts with explicit imports, semantic constraints, static inspection, and mechanical migration from inline definitions.

See the Quick Start, Schema Contracts, Secrets, and CLI Commands for current behavior.

Next

The next design work covers diagnostics and resolution tracing around the reusable contract. The interfaces below are not release commitments.

The later semantic diff and audit work will build on the current external schema. A semantic schema diff would describe changes that require configuration updates before deployment. It complements fuse --diff, which compares generated artifacts.

Explain resolution

Show why a variable has its final value without exposing secret material.

Proposed interface:

dotenv-fusion explain DATABASE_URL --var ENV=production
dotenv-fusion explain API_KEY -f .env-fuse --format json

The result should identify:

  • the defining file and line;
  • the import chain and active conditions;
  • defaults, overrides, and compilation variables that affected resolution;
  • whether the value is secret or derived from a secret;
  • the selected source URI and whether its backend was resolved.

Secret and secret-derived values remain redacted in every output format, even when an authorized run resolves their backend for validation.

JSON output should expose the same facts through a stable, versioned schema.

Structured outputs

Add machine-readable and publishable formats to existing inspection commands.

Proposed interface:

dotenv-fusion check --format json
dotenv-fusion docs --format markdown
dotenv-fusion docs --format json
dotenv-fusion template --format env-example
dotenv-fusion template --format markdown

Requirements:

  • human-readable output remains the default;
  • JSON contracts are stable enough for CI and editor integrations;
  • Markdown output can be published without manual cleanup;
  • secret and secret-derived values are never included in generated reports.

fuse --diff already provides deterministic artifact comparison. A separate freshness feature should be added only if a concrete workflow requires behavior that content comparison cannot provide.

Later

These features fit the current architecture but are not scheduled.

Smart template generation

Infer a draft configuration contract from an existing .env while keeping the result reviewable.

Proposed interface:

dotenv-fusion template --smart -f .env > .env.example
dotenv-fusion template --smart --emit-defs -f .env > .env-fuse

Inference may suggest primitive types, conservative validation rules, defaults, and likely secret classifications. It must remain opt-in and explain each suggestion. Secret-like values must be omitted from public output.

Deterministic secret extraction is already handled by dotenv-fusion migrate secret; smart templates should complement that workflow rather than duplicate it.

Additional secret backends

Future backends extend the existing #@def ... source="URI" contract. Candidates include:

  • mounted Docker or Kubernetes secret files beneath a confined store root;
  • GnuPG-encrypted dotenv bundles with selector semantics matching age;
  • gopass entries with explicit stores and deterministic field selection.

Each backend needs an allowlisted adapter, sanitized errors, bounded reads, well-defined caching, and confinement appropriate to its storage model.

Arbitrary command execution is not a backend. Configuration files must never select Python modules or shell commands to retrieve a secret.

Matrix compilation

Generate several deterministic artifacts from one .env-fuse contract.

Proposed interface:

dotenv-fusion fuse \
  --matrix ENV=development,staging,production \
  --matrix REGION=eu,us \
  --output-dir dist/env

Named targets may be safer when only specific combinations are valid:

dotenv-fusion fuse \
  --target development:ENV=development,REGION=eu,output=.env.development \
  --target production-eu:ENV=production,REGION=eu,output=.env.production.eu

Matrix compilation must fail before writing if outputs collide or any target is invalid. Dry-run and diff behavior should apply to the whole set.

Its secret policy must match fuse: resolving a source into an artifact writes plaintext by design, review output remains redacted, and exec is preferred when the consumer does not require a file.

Exploring

These ideas need stronger use cases and design work before entering the planned roadmap.

Expressions and string transformations

Computed values and Bash-like transformations could reduce duplication, but they would add a second expression language and increase the trusted surface of .env-fuse. Any proposal must remain deterministic, sandboxed, and compatible with the zero-dependency core.

Variable aliases and removal

Aliases or an #@unset directive may help legacy migrations. Their behavior must be defined against first-wins parsing, imports, source-backed values, and environment override rules before syntax is selected.

Environment inheritance

Explicit named environments could make large projects easier to navigate, but the design must demonstrate a benefit beyond the existing import and condition model.

Design rules and current non-goals

Future work should preserve these constraints:

  • New directives use the #@ prefix so ordinary dotenv readers treat them as comments.
  • Existing files and CLI behavior remain backward compatible unless a documented breaking release says otherwise.
  • The core stays dependency-free; optional integrations remain isolated.
  • Secret backends extend source="URI" through allowlisted adapters.
  • Configuration never executes an arbitrary command or imports an arbitrary Python module.
  • fuse may deliberately create a protected plaintext artifact; exec is the path for direct process delivery without that artifact.
  • Remote imports and embedded #@encrypt or #@decrypt directives are not part of the current roadmap. They introduce trust, caching, and key-management models that the existing local-file and source-backend contracts avoid.
  • Every new inspection or generation path preserves secret redaction and has focused tests for its public contract.

Contributing

Open a proposal in GitLab Issues with the user problem, expected behavior, security boundaries, and an example of the smallest useful interface.