dotenv-tool/README.md

The command line tool to read, manipulate and update .env files.

Features

• by default, preserves white spaces, line breaks and comments
• supports reading and updating .end files
• can read and write to stdin/stdout to be used in shell as a part of commands pipeline
• support multiple input files for updates as well as list of arguments at end of command
• supports single and double quoted values
• support comment lines and comments at end of variables
• can do smart append to preserve logical groups of variables
• can beautify (normalize) file layout
• command line can work in resilient mode, ignoring parsing errors

Setup

npm install -g dotenv-tool --registry https://npm.dzienia.pl

Command Line

If input or output file(s) are not specified, dotenv-tool will use stdin or stdout

$ echo -n "VAR1=value1\nVAR2=value2" | dotenv-tool read VAR1 > result.txt
$ cat result.txt
value1

By default, new keys are added at end of resulting file. This can be changed by options:

• --onlyUpdate - prevents new keys to be appended, only existing keys are updated
• --smartAppend - finds most similar group of variables and appends new variables between them, preserving alphabetical order.

To operate on files, specify input file(s) with -i and output file with -o. To modify first input file use -m.

Modify files

$ dotenv-tool -h

Usage: dotenv-tool [options] [command] [paramsToSet...]

Tool to read and update .env files

Arguments:
  paramsToSet                  space separated list of additional envs to set, in format key=value (default: "")

Options:
  -v, --version                output the version number
  -i, --files <filePaths...>   Input file(s)
  -o, --outputFile <filePath>  Output file
  -m, --modify                 Modify first input file
  -b, --beautify               Beautifies resulting env file
  -u, --onlyUpdate             Only updates existing values, without appending new values
  -p, --smartAppend            Smart appends variables depending on their names
  -r, --resilient              Ignore files that cannot be read during update
  -s, --silent                 Mute all messages and errors
  -h, --help                   display help for command

Commands:
  get [options] <key>          Returns given variable from env file (if specified)

Read prop from file

$ dotenv-tool get -h

Usage: dotenv-tool get [options] <key>

Returns given variable from env file (if specified)

Arguments:
  key                    env variable name a.k.a. key

Options:
  -f, --file <filePath>  Input file to parse (if not given, stdio is used)
  -h, --help             display help for command

API

Internally, library parses into and manipulates on array of tokens Token[]:

• VariableToken holding contents of line with variable
• SimpleToken - for new lines, white space lines or comment lines.

To parse .env string, use parseMultiLine, to update list of tokens use update, to convert token list back into .env string use stringifyTokens.

import { parseMultiLine } from 'dotenv-tool'

const tokens = parseMultiLine("VAR1=value1\nVAR2=value2");
const updatedTokens = update(tokens, { name: 'VAR1', value: 'new value', comment: ' # optional comment' });
console.log(stringifyTokens(updatedTokens))

update

function update(tokens: Token[], updateWith: VariableToUpdate[], config?: Config): Token[];

For convenience, update can get list of updates (updateWith argument) in three different formats:

• Tuple [string, string | null] - with key on position 0 and value on position 1
• Simple object Variable type - contains key, value and optional comment
• Token VariableToken type - useful when updating with result of parsing other .env strings

update(tokens, [['VAR1', 'new value'], ['VAR2', null]])
update(tokens, [ { name: 'VAR1', value: 'new value' }])
update(tokens, [ 
  { 
    token: TokenType.VARIABLE,
    name: 'VAR1', 
    value: 'new value',
    beginning: '',
    equals: ' = ', // extra space around =
    quote: '"',    // value will be inside double quotes
    ending: '   '  // extra white space at end of line
    comment: ''
  }
])

If new value is null - variable will be deleted, if it is empty string or undefined - it will be left empty (VAR=)

Configuration

Both update as well as stringifyTokens take config parameter:

type Config = {
    beautify?: boolean;            // if true, output will be beautified/normalized. Default: false
    enforceNewLineEnd?: boolean;   // if true, output will have ensured \n character at end. Default: true
    modifyMode?: ModifyMode;       // decide if new keys should or should not be added, and where. Default: ModifyMode.APPEND
};