TOML to .env

What this tool is used for

• Producing environment variables from a TOML config for a container or a platform.
• Flattening nested TOML tables into the prefixed names a twelve-factor app expects.
• Converting local configuration into the form a deployment target reads.
• Generating a `.env` file from a checked-in TOML template.
• Comparing a TOML config against an existing environment file.

Frequently Asked Questions

How do TOML tables become variable names?

Flattened with an underscore and upper-cased: a `[database]` table containing `host` becomes `DATABASE_HOST`. That matches the convention almost every framework uses to map environment variables back onto nested configuration.

Do the types survive?

No. TOML has real types — integers, floats, booleans, dates, arrays — and an environment variable is always a string. `port = 8080` becomes `PORT=8080` and your application has to parse it back, which is where a stray space or quote causes trouble.

What happens to arrays?

They have no native representation, so they are joined into one delimited string. Whoever reads the value has to know how to split it — which is why a list in an environment variable is a convention between two pieces of code, not a format.

Should values be quoted in a .env file?

Quote anything containing a space, a `#`, or a newline — `#` starts a comment in most dotenv parsers and will truncate an unquoted value. Note that `.env` is not standardised: quoting, escaping and multi-line rules differ between implementations.

Is .env safe for secrets?

Only in local development, and only if it is gitignored. It sits unencrypted on disk and every child process inherits it, so production secrets belong in a secrets manager. Committing a `.env` is one of the most common credential leaks on GitHub.

How are nested tables represented in a flat env file?

By joining the path with underscores and upper-casing — `database.host` becomes `DATABASE_HOST`. It is lossy: a key already containing an underscore becomes indistinguishable from a nesting boundary.

Common errors and gotchas

• Committing the output, which usually holds secrets and is gitignored for that reason.
• Losing TOML's real types, since every environment variable is a string.
• Producing names that are not valid environment variable identifiers, such as ones containing a dash.
• Flattening an array into a single value with no agreed separator, which the consumer then has to guess.
• Overlooking that a very long value may exceed a platform's environment size limit.