Usage: env-cmd [options] -- <command> [...args]Options: -v, --version output the version number -e, --environments [envs...] The rc file environment(s) to use -f, --file [path] Custom env file path or .rc file path if '-e' used (default path: ./.env or ./.env-cmdrc.(js|cjs|mjs|json)) -x, --expand-envs Replace $var and ${var} in args and command with environment variables --recursive Replace $var and ${var} in env file with the referenced environment variable --fallback Fallback to default env file path, if custom env file path not found --no-override Do not override existing environment variables --silent Ignore any env-cmd errors and only fail on executed program failure. --use-shell Execute the command in a new shell with the given environment --verbose Print helpful debugging information -h, --help display help for command
🔬 Advanced Usage
.rc file usage
For more complex projects, a .env-cmdrc file can be defined in the root directory and supports
as many environments as you want. Simply use the -e flag and provide which environments you wish to
use from the .env-cmdrc file. Using multiple environment names will merge the environment variables
together. Later environments overwrite earlier ones in the list if conflicting environment variables
are found.
./node_modules/.bin/env-cmd -e production -- node index.js# Or for multiple environments (where `production` vars override `test` vars,# but both are included)./node_modules/.bin/env-cmd -e test,production -- node index.js
--no-override option
Prevents overriding of existing environment variables on process.env and within the current
environment.
--fallback file usage option
If the .env file does not exist at the provided custom path, then use the default
fallback location ./.env env file instead.
--use-shell
Executes the command within a new shell environment. This is useful if you want to string multiple
commands together that share the same environment variables.
EnvCmd supports reading from asynchronous .env files. Instead of using a .env file, pass in a .js
file that exports either an object or a Promise resolving to an object ({ ENV_VAR_NAME: value, ... }). Asynchronous .rc
files are also supported using .js file extension and resolving to an object with top level environment
names ({ production: { ENV_VAR_NAME: value, ... } }).
EnvCmd supports expanding $var values passed in as arguments to the command. The allows a user
to provide arguments to a command that are based on environment variable values at runtime.
NOTE: You must escape the $ character with \ or your terminal might try to auto expand it before passing it to env-cmd.
Terminal
# $VAR will be expanded into the env value it contains at runtime./node_modules/.bin/env-cmd -x -- node index.js --arg=\$VAR
or in package.json (use \\ to insert a literal backslash)
EnvCmd supports the --silent flag the suppresses all errors generated by env-cmd
while leaving errors generated by the child process and cli signals still usable. This
flag is primarily used to allow env-cmd to run in environments where the .env
file might not be present, but still execute the child process without failing
due to a missing file.
💿 Examples
You can find examples of how to use the various options above by visiting
the examples repo env-cmd-examples.
💽️ Environment File Formats
These are the currently accepted environment file formats. If any other formats are desired please create an issue.
.env as key=value
.env.json Key/value pairs as JSON
.env.js JavaScript file exporting an object or a Promise that resolves to an object
.env-cmdrc as valid json or .env-cmdrc.json in execution directory with at least one environment { "dev": { "key1": "val1" } }
.env-cmdrc.js JavaScript file exporting an object or a Promise that resolves to an object that contains at least one environment
🗂 Path Rules
This lib attempts to follow standard bash path rules. The rules are as followed:
Home Directory = /Users/test
Working Directory = /Users/test/Development/app
Type
Input Path
Expanded Path
Absolute
/some/absolute/path.env
/some/absolute/path.env
Home Directory with ~
~/starts/on/homedir/path.env
/Users/test/starts/on/homedir/path.env
Relative
./some/relative/path.env or some/relative/path.env
noOverride { boolean }: Prevent .env file vars from overriding existing process.env vars (default: false)
silent { boolean }: Ignore any errors thrown by env-cmd, used to ignore missing file errors (default: false)
useShell { }: Runs command inside a new shell instance (default: )
GetEnvVars
A function that parses environment variables from a .env or a .rc file
options { object }
envFile { object }
filePath { string }: Custom path to .env file to read from (defaults to: ./.env)
fallback { boolean }: Should fall back to default ./.env file if custom path does not exist
rc { object }
environments { string[] }: List of environment to read from the .rc file
filePath { string }: Custom path to the .rc file (defaults to: ./.env-cmdrc(|.js|.json))
verbose { boolean }: Prints extra debug logs to console.info (default: false)
Returns { Promise<object> }: key is env var name and value is the env var value
🧙 Why
Because sometimes it is just too cumbersome passing a lot of environment variables to scripts. It is
usually just easier to have a file with all the vars in them, especially for development and testing.
🚨Do not commit sensitive environment data to a public git repo! 🚨
🧬 Related Projects
cross-env - Cross platform setting of environment scripts
📋 Contributing Guide
I welcome all pull requests. Please make sure you add appropriate test cases for any features
added. Before opening a PR please make sure to run the following scripts:
npm run lint checks for code errors and format according to ts-standard
npm test make sure all tests pass
npm run test-cover make sure the coverage has not decreased from current master
boolean
false
verbose { boolean }: Prints extra debug logs to console.info (default: false)
Returns { Promise<object> }: key is env var name and value is the env var value