dotenv-subst

A CLI tool and library for interpolating variables in any file, using .env files (or any file structured as key=value pairs) to define the replacement values.

It leverages Dotenvx to read variables values from file(s) and applies them to interpolate any provided static file(s). This allows you to use variables from key=value configuration files in both runtime code and build-time files—where it wouldn't be possible to access those variables from the runtime environment.

📖 Check out the dedicated documentation site.

🚀 Features

• Simple & Lightweight – No other runtime dependencies besides Dotenvx
• Works with any File Format – Interpolates variables in any text-based file (e.g. md, json, yml etc.)
• Flexible & Configurable – Supports various interpolation syntaxes and configuration options
• CLI & API Support – Use it in scripts, pipelines, or as a library directly in code

📦 Installation

Npm

# install as global package
npm install -g dotenv-subst

# or as local dependency
npm install -D dotenv-subst

💻 CLI Usage

$ dotenv-subst [options] <source...>

Each positional argument is interpreted as the path to a source file containing variable placeholders for interpolation. All the available options are documented in the dedicated section further down.

In-place Replacement Example

With these files in your working directory:

📄 ./.env.test

USERNAME=jaydoe
GREETING=Hello

📄 ./my-test-file.md

{{GREETING}}, my name is ${USERNAME}.

Running the following command:

dotenv-subst --env-file=.env.test my-test-file.md

Updates the file with the interpolated content:

📄 ./my-test-file.md

Hello, my name is jaydoe.

Custom Output File Path Example

Given the same starting files of the previous example, if the following command is run instead:

dotenv-subst --env-file=.env.test --output=my-output.md my-test-file.md

The interpolated output is written to my-output.md, while the original source file my-test-file.md is left intact.

[!TIP] 📖 For a more comprehensive list of usage examples, head over to the dedicated CLI Usage Examples section of the documentation site.

🛠️ CLI Options

| Option | Default | Description | | :--------------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | | -o, --output <path> | same as source file | Optional output file path–if omitted defaults to in-place interpolation⚠️ Only applicable when a single source file is provided | | -f, --env-file <paths...> | [] | Path(s) to your env file(s)ℹ️ Forwarded to dotenvx without additional processing | | --ignore-unset-vars | false | Do not abort if source file(s) contain variables not defined in env file(s)(by default, throws the first unset variable error encountered) | | --encoding <name> | 'utf-8' | Encoding of your source and env file(s)ℹ️ Both used internally and forwarded to dotenvx | | --env-keys-file <path> | same as env file | Path to your .env.keys fileℹ️ Forwarded to dotenvx without additional processing | | --overload | false | Override existing env variablesℹ️ Forwarded to dotenvx without additional processing | | --convention <name> | undefined | Load a .env convention (available conventions: ['nextjs', 'flow'])ℹ️ Forwarded to dotenvx without additional processing | | -v, --verbose | false | Sets log level to verboseℹ️ Both used internally and forwarded to dotenvx | | -q, --quiet | false | Sets log level to errorℹ️ Both used internally and forwarded to dotenvx | | -V, --version | – | Output the package version number | | -h, --help | – | Display help info for the command |

For more details on options forwarded to dotenvx, see the official Dotenvx CLI Docs.

✍️ Variable Interpolation Syntaxes

You can use any of the following syntax styles for interpolation placeholders in your source files:

| Syntax | Example | | :--------------- | :--------------- | | Shell-style | ${VAR_NAME} | | Handlebars-style | {{VAR_NAME}} | | GH Actions-style | ${{VAR_NAME}} |

[!NOTE] This tool imposes no strict rules on variables syntax:

• Variable names can use any text case (e.g.: ${FOO}, {{bar}}, ${{fooBar}})
• Whitespace inside brackets is ignored (e.g.: ${ foo }, {{foo }}, ${{ foo}})

🧑‍💻 Contribution

Contributions are welcome! Also please feel free to submit issues, bug reports, or requests in the Issues section.

⚖️ License

This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.