dotenv-flow CLI

1.1.1 · maintenance · verified Wed Apr 22

dotenv-flow-cli is a command-line interface (CLI) tool designed to execute shell commands with environment variables loaded from `.env` files using `dotenv-flow`'s sophisticated loading logic. It automatically processes different `.env` files based on the `NODE_ENV` and other `dotenv-flow` conventions, allowing for environment-specific configurations (e.g., `.env.development`, `.env.production`, `.env.local`). The current stable version is 1.1.1, with the last publish date over two years ago, suggesting a maintenance or stable cadence driven by its upstream dependencies, `dotenv-flow` and `dotenv-expand`. Its key differentiator from `dotenv-cli` is the reliance on `dotenv-flow`'s specific cascading `.env` file loading strategy, which includes support for `development`, `test`, `production`, and `.local` overrides, along with automatic variable expansion. It is intended as a direct wrapper, providing a convenient executable for managing environment variables for CLI commands.

Common errors

```
command not found: dotenv-flow
```
cause `dotenv-flow-cli` is not installed globally or is not in the system's PATH.

fix Install globally using `npm install -g dotenv-flow-cli` or `yarn global add dotenv-flow-cli`. Alternatively, use `npx dotenv-flow <command>` for ad-hoc execution without global installation.
```
Environment variable 'MY_VAR' is not set, but I defined it in .env
```
cause Incorrect `.env` file naming convention, `NODE_ENV` not matching, or files are not located in the current working directory or the specified path.

fix Verify `.env` filenames adhere to `dotenv-flow` conventions (e.g., `.env`, `.env.development`, `.env.production`, `.env.local`). Ensure `NODE_ENV` is correctly set before running the `dotenv-flow` command, or use the `-p` option to specify the correct directory.

Warnings

gotcha Arguments intended for the underlying command may be parsed by `dotenv-flow-cli` instead, leading to unexpected behavior or lost arguments.
Fix: Always use the `--` separator before the actual command if it takes additional arguments (e.g., `dotenv-flow -- my-command -p something`).
gotcha Misunderstanding `dotenv-flow`'s specific file loading order (e.g., `.env.development.local` overrides `.env.development`, which overrides `.env`) can lead to environment variables not being what's expected.
Fix: Refer to the comprehensive `dotenv-flow` documentation to understand the exact file loading precedence and override rules.
gotcha Variable expansion (interpolation) is automatically enabled using `dotenv-expand` under the hood. This can be unexpected if users are accustomed to `dotenv-cli` without explicit expansion.
Fix: Be aware that variables like `APP_URL=http://${IP}:${PORT}` will automatically resolve. If this behavior is undesired, ensure variables are properly escaped or consider alternative tools.
gotcha The package `dotenv-flow-cli` itself has not been updated in over two years (last published January 7, 2024), indicating a stable but potentially unmaintained state.
Fix: While functional, major updates or compatibility with newer Node.js versions or dependency changes might be slow. Consider pinning specific versions of underlying dependencies like `dotenv-flow` if stability is critical.

Install

npm install dotenv-flow-cli npm
yarn add dotenv-flow-cli yarn
pnpm add dotenv-flow-cli pnpm

Imports

dotenv-flow CLI execution
```
dotenv-flow <command> [args...]
```
Primary usage is via direct shell command invocation in `package.json` scripts or terminal.
dotenv-flow with custom path
```
dotenv-flow -p path/to/project <command> [args...]
```
Use the `-p` or `--path` option to specify an alternative directory where `.env*` files are located.
dotenv-flow with command arguments
wrong:
```
dotenv-flow <command> <command-arguments...>
```
correct:
```
dotenv-flow -- <command> <command-arguments...>
```
Always use the `--` separator before the command if the command itself takes arguments, to prevent `dotenv-flow-cli` from misinterpreting them.

Quickstart

Demonstrates global installation, creation of layered `.env` files, and executing Node.js commands to show how `dotenv-flow-cli` loads environment variables based on `NODE_ENV` and `.local` overrides.

npm install -g dotenv-flow-cli

# Create example .env files
echo "APP_NAME=MyFlowApp" > .env
echo "API_KEY=dev_123" > .env.development
echo "API_KEY=prod_xyz" > .env.production
echo "DEBUG_MODE=true" > .env.development.local

# Run a command in development environment
NODE_ENV=development dotenv-flow -- node -e "console.log('App Name:', process.env.APP_NAME); console.log('API Key:', process.env.API_KEY); console.log('Debug Mode:', process.env.DEBUG_MODE);"

# Run a command in production environment
NODE_ENV=production dotenv-flow -- node -e "console.log('App Name:', process.env.APP_NAME); console.log('API Key:', process.env.API_KEY); console.log('Debug Mode:', process.env.DEBUG_MODE);"

view raw JSON →