File: //home/arjun/projects/propbase/propbase_website/node_modules/env-cmd/README.md
[](https://travis-ci.org/toddbluhm/env-cmd)
[](https://coveralls.io/github/toddbluhm/env-cmd?branch=master)
[](https://www.npmjs.com/package/env-cmd)
[](https://www.npmjs.com/package/env-cmd)
[](https://www.npmjs.com/package/env-cmd)
[](https://github.com/toddbluhm/ts-standard)
[](https://greenkeeper.io/)
# env-cmd
A simple node program for executing commands using an environment from an env file.
## 💾 Install
`npm install env-cmd` or `npm install -g env-cmd`
## ⌨️ Basic Usage
**Environment file `./.env`**
```text
# This is a comment
ENV1=THANKS
ENV2=FOR ALL
ENV3=THE FISH
```
**Package.json**
```json
{
"scripts": {
"test": "env-cmd mocha -R spec"
}
}
```
**Terminal**
```sh
./node_modules/.bin/env-cmd node index.js
```
### Using custom env file path
To use a custom env filename or path, pass the `-f` flag. This is a major breaking change from prior versions < 9.0.0
**Terminal**
```sh
./node_modules/.bin/env-cmd -f ./custom/path/.env node index.js
```
## 📜 Help
```text
Usage: _ [options] <command> [...args]
Options:
-v, --version output the version number
-e, --environments [env1,env2,...] The rc file environment(s) to use
-f, --file [path] Custom env file path (default path: ./.env)
--fallback Fallback to default env file path, if custom env file path not found
--no-override Do not override existing environment variables
-r, --rc-file [path] Custom rc file path (default path: ./.env-cmdrc(|.js|.json)
--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
-x, --expand-envs Replace $var in args and command with environment variables
-h, --help output usage information
```
## 🔬 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.
**.rc file `./.env-cmdrc`**
```json
{
"development": {
"ENV1": "Thanks",
"ENV2": "For All"
},
"test": {
"ENV1": "No Thanks",
"ENV3": "!"
},
"production": {
"ENV1": "The Fish"
}
}
```
**Terminal**
```sh
./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.
**Terminal**
```sh
./node_modules/.bin/env-cmd -f ./test/.env --use-shell "npm run lint && npm test"
```
### Asynchronous env file support
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, ... } }`).
**Terminal**
```sh
./node_modules/.bin/env-cmd -f ./async-file.js node index.js
```
### `-x` expands vars in arguments
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.
**Terminal**
```sh
# $USER will be expanded into the env value it contains at runtime
./node_modules/.bin/env-cmd -x node index.js --user=$USER
```
### `--silent` suppresses env-cmd errors
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](https://github.com/toddbluhm/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` | `/Users/test/Development/app/some/relative/path.env` |
| Relative with parent dir | `../some/relative/path.env` | `/Users/test/Development/some/relative/path.env` |
## 🛠 API Usage
### `EnvCmd`
A function that executes a given command in a new child process with the given environment and options
- **`options`** { `object` }
- **`command`** { `string` }: The command to execute (`node`, `mocha`, ...)
- **`commandArgs`** { `string[]` }: List of arguments to pass to the `command` (`['-R', 'Spec']`)
- **`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)`)
- **`options`** { `object` }
- **`expandEnvs`** { `boolean` }: Expand `$var` values passed to `commandArgs` (default: `false`)
- **`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`** { `boolean` }: Runs command inside a new shell instance (default: `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
### `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`](https://github.com/kentcdodds/cross-env) - Cross platform setting of environment scripts
## 🎊 Special Thanks
Special thanks to [`cross-env`](https://github.com/kentcdodds/cross-env) for inspiration (uses the
same `cross-spawn` lib underneath too).
## 📋 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](https://github.com/toddbluhm/ts-standard)
- `npm test` make sure all tests pass
- `npm run test-cover` make sure the coverage has not decreased from current master