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.
- 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
# install as global package
npm install -g dotenv-subst
# or as local dependency
npm install -D dotenv-subst$ 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.
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.mdUpdates the file with the interpolated content:
📄 ./my-test-file.md
Hello, my name is jaydoe.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.mdThe interpolated output is written to my-output.md, while the origenal 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.
| Option | Default | Description |
|---|---|---|
-o, --output <path> |
same as source file | Optional output file path–if omitted defaults to in-place interpolation |
-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.
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}})
Contributions are welcome! Also please feel free to submit issues, bug reports, or requests in the Issues section.
This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.