{"id":13452469,"url":"https://github.com/toddbluhm/env-cmd","last_synced_at":"2025-05-14T00:09:20.941Z","repository":{"id":41063233,"uuid":"65864451","full_name":"toddbluhm/env-cmd","owner":"toddbluhm","description":"Setting environment variables from a file","archived":false,"fork":false,"pushed_at":"2025-03-25T11:59:30.000Z","size":504,"stargazers_count":1785,"open_issues_count":42,"forks_count":65,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-08T18:44:20.151Z","etag":null,"topics":["command-line-tool","cross-platform","environment-variables","environments","nodejs","typescript","utilities","variables"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/env-cmd","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toddbluhm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["toddbluhm"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2016-08-17T01:00:47.000Z","updated_at":"2025-05-04T13:27:42.000Z","dependencies_parsed_at":"2022-08-10T01:29:43.548Z","dependency_job_id":"495a1303-409c-493a-9b7e-5554608b6b4d","html_url":"https://github.com/toddbluhm/env-cmd","commit_stats":{"total_commits":120,"total_committers":20,"mean_commits":6.0,"dds":0.275,"last_synced_commit":"8f35b71651f6a78710308ff38ab30896ea72ee8b"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddbluhm%2Fenv-cmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddbluhm%2Fenv-cmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddbluhm%2Fenv-cmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toddbluhm%2Fenv-cmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toddbluhm","download_url":"https://codeload.github.com/toddbluhm/env-cmd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254044137,"owners_count":22005085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","cross-platform","environment-variables","environments","nodejs","typescript","utilities","variables"],"created_at":"2024-07-31T07:01:24.976Z","updated_at":"2025-05-14T00:09:15.932Z","avatar_url":"https://github.com/toddbluhm.png","language":"TypeScript","readme":"[![Linux Tests](https://github.com/toddbluhm/env-cmd/workflows/linux%20tests/badge.svg)](https://github.com/toddbluhm/env-cmd/actions?query=workflow%3A%22linux%20tests%22)\n[![Windows Tests](https://github.com/toddbluhm/env-cmd/workflows/windows%20tests/badge.svg)](https://github.com/toddbluhm/env-cmd/actions?query=workflow%3A%22windows%20tests%22)\n[![Coverage Status](https://badgen.net/coveralls/c/github/toddbluhm/env-cmd)](https://coveralls.io/github/toddbluhm/env-cmd?branch=master)\n[![npm](https://badgen.net/npm/v/env-cmd)](https://www.npmjs.com/package/env-cmd)\n[![npm](https://badgen.net/npm/dm/env-cmd)](https://www.npmjs.com/package/env-cmd)\n[![License](https://badgen.net/github/license/toddbluhm/env-cmd)](https://github.com/toddbluhm/env-cmd/blob/master/LICENSE)\n[![Typescript-ESLint](https://badgen.net/badge/code%20style/typescript-eslint/blue?icon=typescript)](https://github.com/typescript-eslint/typescript-eslint)\n\n# env-cmd\n\nA simple node program for executing commands using an environment from an env file.\n\n## 💾 Install\n\n`npm install env-cmd` or `npm install -g env-cmd`\n\n## ⌨️ Basic Usage\n\n**Environment file `./.env`**\n\n```text\n# This is a comment\nENV1=THANKS\nENV2=FOR ALL\nENV3=THE FISH\n```\n\n**Package.json**\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"env-cmd -- mocha -R spec\"\n  }\n}\n```\n\n**Terminal**\n\n```sh\n./node_modules/.bin/env-cmd -- node index.js\n```\n\n### Using custom env file path\n\nTo use a custom env filename or path, pass the `-f` flag. This is a major breaking change from prior versions \u003c 9.0.0\n\n**Terminal**\n\n```sh\n./node_modules/.bin/env-cmd -f ./custom/path/.env -- node index.js\n```\n\n## 📜 Help\n\n```text\nUsage: env-cmd [options] -- \u003ccommand\u003e [...args]\n\nOptions:\n  -v, --version                       output the version number\n  -e, --environments [env1,env2,...]  The rc file environment(s) to use\n  -f, --file [path]                   Custom env file path (default path: ./.env)\n  --fallback                          Fallback to default env file path, if custom env file path not found\n  --no-override                       Do not override existing environment variables\n  -r, --rc-file [path]                Custom rc file path (default path: ./.env-cmdrc(|.js|.json)\n  --silent                            Ignore any env-cmd errors and only fail on executed program failure.\n  --use-shell                         Execute the command in a new shell with the given environment\n  --verbose                           Print helpful debugging information\n  -x, --expand-envs                   Replace $var in args and command with environment variables\n  -h, --help                          output usage information\n```\n\n## 🔬 Advanced Usage\n\n### `.rc` file usage\n\nFor more complex projects, a `.env-cmdrc` file can be defined in the root directory and supports\nas many environments as you want. Simply use the `-e` flag and provide which environments you wish to\nuse from the `.env-cmdrc` file. Using multiple environment names will merge the environment variables\ntogether. Later environments overwrite earlier ones in the list if conflicting environment variables\nare found.\n\n**.rc file `./.env-cmdrc`**\n\n```json\n{\n  \"development\": {\n    \"ENV1\": \"Thanks\",\n    \"ENV2\": \"For All\"\n  },\n  \"test\": {\n    \"ENV1\": \"No Thanks\",\n    \"ENV3\": \"!\"\n  },\n  \"production\": {\n    \"ENV1\": \"The Fish\"\n  }\n}\n```\n\n**Terminal**\n\n```sh\n./node_modules/.bin/env-cmd -e production -- node index.js\n# Or for multiple environments (where `production` vars override `test` vars,\n# but both are included)\n./node_modules/.bin/env-cmd -e test,production -- node index.js\n```\n\n### `--no-override` option\n\nPrevents overriding of existing environment variables on `process.env` and within the current\nenvironment.\n\n### `--fallback` file usage option\n\nIf the `.env` file does not exist at the provided custom path, then use the default\nfallback location `./.env` env file instead.\n\n### `--use-shell`\n\nExecutes the command within a new shell environment. This is useful if you want to string multiple\ncommands together that share the same environment variables.\n\n**Terminal**\n\n```sh\n./node_modules/.bin/env-cmd -f ./test/.env --use-shell -- \"npm run lint \u0026\u0026 npm test\"\n```\n\n### Asynchronous env file support\n   \n   EnvCmd supports reading from asynchronous `.env` files. Instead of using a `.env` file, pass in a `.js`\n   file that exports either an object or a `Promise` resolving to an object (`{ ENV_VAR_NAME: value, ... }`). Asynchronous `.rc`\n   files are also supported using `.js` file extension and resolving to an object with top level environment\n   names (`{ production: { ENV_VAR_NAME: value, ... } }`).\n   \n   **Terminal**\n   \n   ```sh\n   ./node_modules/.bin/env-cmd -f ./async-file.js -- node index.js\n   ```\n\n### `-x` expands vars in arguments\n\nEnvCmd supports expanding `$var` values passed in as arguments to the command. The allows a user\nto provide arguments to a command that are based on environment variable values at runtime.\n\n**NOTE:** You must escape the `$` character with `\\` or your terminal might try to auto expand it before passing it to `env-cmd`.\n\n**Terminal**\n\n```sh\n# $VAR will be expanded into the env value it contains at runtime\n./node_modules/.bin/env-cmd -x -- node index.js --arg=\\$VAR\n```\n\nor in `package.json` (use `\\\\` to insert a literal backslash)\n```json\n{\n  \"script\": {\n    \"start\": \"env-cmd -x -- node index.js --arg=\\\\$VAR\"\n  }\n}\n```\n\n\n### `--silent` suppresses env-cmd errors\n\nEnvCmd supports the `--silent` flag the suppresses all errors generated by `env-cmd`\nwhile leaving errors generated by the child process and cli signals still usable. This\nflag is primarily used to allow `env-cmd` to run in environments where the `.env`\nfile might not be present, but still execute the child process without failing\ndue to a missing file.\n\n\n## 💿 Examples\n\nYou can find examples of how to use the various options above by visiting\nthe examples repo [env-cmd-examples](https://github.com/toddbluhm/env-cmd-examples).\n\n## 💽️ Environment File Formats\n\nThese are the currently accepted environment file formats. If any other formats are desired please create an issue.\n\n- `.env` as `key=value`\n- `.env.json` Key/value pairs as JSON\n- `.env.js` JavaScript file exporting an `object` or a `Promise` that resolves to an `object`\n- `.env-cmdrc` as valid json or `.env-cmdrc.json` in execution directory with at least one environment `{ \"dev\": { \"key1\": \"val1\" } }`\n- `.env-cmdrc.js` JavaScript file exporting an `object` or a `Promise` that resolves to an `object` that contains at least one environment\n\n## 🗂 Path Rules\n\nThis lib attempts to follow standard `bash` path rules. The rules are as followed:\n\nHome Directory = `/Users/test`\n\nWorking Directory = `/Users/test/Development/app`\n\n| Type | Input Path | Expanded Path |\n| -- | -- | ------------- |\n| Absolute | `/some/absolute/path.env` | `/some/absolute/path.env` |\n| Home Directory with `~` | `~/starts/on/homedir/path.env` | `/Users/test/starts/on/homedir/path.env` |\n| Relative | `./some/relative/path.env` or `some/relative/path.env` | `/Users/test/Development/app/some/relative/path.env` |\n| Relative with parent dir | `../some/relative/path.env` | `/Users/test/Development/some/relative/path.env` |\n\n## 🛠 API Usage\n\n### `EnvCmd`\n\nA function that executes a given command in a new child process with the given environment and options\n\n- **`options`** { `object` }\n  - **`command`** { `string` }: The command to execute (`node`, `mocha`, ...)\n  - **`commandArgs`** { `string[]` }: List of arguments to pass to the `command` (`['-R', 'Spec']`)\n  - **`envFile`** { `object` }\n    - **`filePath`** { `string` }: Custom path to .env file to read from (defaults to: `./.env`)\n    - **`fallback`** { `boolean` }: Should fall back to default `./.env` file if custom path does not exist\n  - **`rc`** { `object` }\n    - **`environments`** { `string[]` }: List of environment to read from the `.rc` file\n    - **`filePath`** { `string` }: Custom path to the `.rc` file (defaults to: `./.env-cmdrc(|.js|.json)`)\n  - **`options`** { `object` }\n    - **`expandEnvs`** { `boolean` }: Expand `$var` values passed to `commandArgs` (default: `false`)\n    - **`noOverride`** { `boolean` }: Prevent `.env` file vars from overriding existing `process.env` vars (default: `false`)\n    - **`silent`** { `boolean` }: Ignore any errors thrown by env-cmd, used to ignore missing file errors (default: `false`)\n    - **`useShell`** { `boolean` }: Runs command inside a new shell instance (default: `false`)\n    - **`verbose`** { `boolean` }: Prints extra debug logs to `console.info` (default: `false`)\n  - **Returns** { `Promise\u003cobject\u003e` }: key is env var name and value is the env var value\n\n### `GetEnvVars`\n\nA function that parses environment variables from a `.env` or a `.rc` file\n\n- **`options`** { `object` }\n  - **`envFile`** { `object` }\n    - **`filePath`** { `string` }: Custom path to .env file to read from (defaults to: `./.env`)\n    - **`fallback`** { `boolean` }: Should fall back to default `./.env` file if custom path does not exist\n  - **`rc`** { `object` }\n    - **`environments`** { `string[]` }: List of environment to read from the `.rc` file\n    - **`filePath`** { `string` }: Custom path to the `.rc` file (defaults to: `./.env-cmdrc(|.js|.json)`)\n  - **`verbose`** { `boolean` }: Prints extra debug logs to `console.info` (default: `false`)\n- **Returns** { `Promise\u003cobject\u003e` }: key is env var name and value is the env var value\n\n## 🧙 Why\n\nBecause sometimes it is just too cumbersome passing a lot of environment variables to scripts. It is\nusually just easier to have a file with all the vars in them, especially for development and testing.\n\n🚨**Do not commit sensitive environment data to a public git repo!** 🚨\n\n## 🧬 Related Projects\n\n[`cross-env`](https://github.com/kentcdodds/cross-env) - Cross platform setting of environment scripts\n\n## 📋 Contributing Guide\n\nI welcome all pull requests. Please make sure you add appropriate test cases for any features\nadded. Before opening a PR please make sure to run the following scripts:\n\n- `npm run lint` checks for code errors and format according to [ts-standard](https://github.com/toddbluhm/ts-standard)\n- `npm test` make sure all tests pass\n- `npm run test-cover` make sure the coverage has not decreased from current master\n","funding_links":["https://github.com/sponsors/toddbluhm"],"categories":["TypeScript","Uncategorized","typescript",":books: Libraries"],"sub_categories":["Uncategorized","Node"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoddbluhm%2Fenv-cmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoddbluhm%2Fenv-cmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoddbluhm%2Fenv-cmd/lists"}