envkey-cmd

A simple node program for executing commands using an environment from a given ENVKEY

Simply set an ENVKEY variable in the existing environment or provide as a command line argument, and then the given child process will be executed will the full environment corresponding to this ENVKEY

This is a simple wrapper around 'envkey' with all the child process spawn logic forked from 'envkey-cmd'

💾 Install

npm install envkey-cmd or npm install -g envkey-cmd

⌨️ Basic Usage

Environment

ENVKEY=wYv78UmHsfEu6jSqMZrU-3w1kwyF35nRYwsAJ

Package.json

{
  "scripts": {
    "test": "envkey-cmd mocha -R spec"
  }
}

Terminal

./node_modules/.bin/envkey-cmd node index.js

📜 Help

Usage: _ [options] <command> [...args]

Options:
  -v, --version                       output the version number
  -e, --envkey [ENVKEY]               The ENVKEY to use; defaults to process.env.ENVKEY
  --permitted [var1,var1,...]         whitelist of permitted vars (useful for client-side config) - defaults to  all
  --no-override                       Do not override existing environment variables
  --silent                            Ignore any envkey-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

Using ENVKEY provided in command line

Terminal

./node_modules/.bin/envkey-cmd -e ENVKEY=wYv78UmHsfEu6jSqMZrU-3w1kwyF35nRYwsAJ node index.js

--permitted option

Whitelist of permitted vars (useful for client-side config) - defaults to all

./node_modules/.bin/envkey-cmd -e ENVKEY=wYv78UmHsfEu6jSqMZrU-3w1kwyF35nRYwsAJ --permitted FIREBASE_TOKEN,FIREBASE_URI node index.js

--no-override option

Prevents overriding of existing environment variables on process.env and within the current environment.

--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

./node_modules/.bin/envkey-cmd -f ./test/.env --use-shell "npm run lint && npm test"

-x expands vars in arguments

EnvKeyCmd 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 envkey-cmd.

Terminal

# $VAR will be expanded into the env value it contains at runtime
./node_modules/.bin/envkey-cmd -x node index.js --arg=\$VAR

or in package.json (use \\ to insert a literal backslash)

{
  "script": {
    "start": "envkey-cmd -x node index.js --arg=\\$VAR"
  }
}

--silent suppresses envkey-cmd errors

EnvKeyCmd supports the --silent flag the suppresses all errors generated by envkey-cmd while leaving errors generated by the child process and cli signals still usable. This flag is primarily used to allow envkey-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.

💽️ ENVKEYS

An addition variable ENVKEYS is supplied in the provided environment with the keynames of all the variables downloaded from the ENVKEY (filtered to the permitted whitelist if provided).

This can be useful for providing to webpack or other utilities that need to know which of the process.env variables to use.

const webpack = require('webpack')

const secretKeys = process.env.ENVKEYS.split(',').reduce((accum, key) => {
    accum[key] = false
    return accum
}, {})

const plugins = [
    new webpack.EnvironmentPlugin({
        ...secretKeys,
        NODE_ENV: process.env.NODE_ENV || 'production'
    })
]

💽️ Environment Files

If you want to provide ENVKEY in an environment file and/or include other environment variables not provided from the cloud ENVKEY, then use env-cmd right before this program.

Package.json

{
  "scripts": {
    "test": "env-cmd -f ../.config/env-secrets.json envkey-cmd mocha -R spec"
  }
}

🗂 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

EnvKeyCmd

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'])
  • envKey { string }: The ENVKEY to use (defaults to process.env.ENVKEY)
  • permitted { string[] }: Whitelist of environment variables to select from the downloaded environment
  • 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 envkey-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<Record<string, string>> }: key is env var name and value is the env var value

GetEnvVars

A function that parses environment variables from a given ENVKEY

{ envKey: string, permitted?: string[], verbose?: boolean }

• options { object }
  • envKey { string }: The ENVKEY to use (defaults to process.env.ENVKEY)
  • permitted { string[] }: Whitelist of environment variables to select from the downloaded environment
  • verbose { boolean }: Prints extra debug logs to console.info (default: false)
• Returns { Promise<Record<string, string>> }: key is env var name and value is the env var value

🧙 Why

Because scripts shouldnt have to know that the environment variables came from ENVKEY; they just expect them to be there. The standard ENVKEY approach requires evaling a shell script from Github or writing a custom node program that calls 'envkey', whereas this is a standard NPM package that just works wherever you can execute a shell script.

🧬 Related Projects

env-cmd - Original source without ENVKEY envkey - The Node wrapper around the ENVKEY cloud fetch logic envkey-source - The equivalent logic but requires multiple steps to download the script and eval it, whereas envkey-cmd can just be included as an npm dependency cross-env - Cross platform setting of environment scripts

🎊 Special Thanks

Special thanks to envkey-cmd for all the hard work, envkey for the custom fetch logic that works on multiple platforms, and cross-env for inspiration (uses the same cross-spawn lib underneath too

📋 Contributing Guide

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