dotenv-tool/README.md

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

## Features

* by default, preserves white spaces, line breaks and comments
* supports reading and updating .env files
* can parse .env file into JSON format
* when parsing checks format validity and report error line number
* 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

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

```bash
$ 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 disable updating (overwriting) existing keys, and only append (supplement with) new keys, use `--onlyAppend`

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

### Modify files

```bash
$ dotenv-tool -h
```

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

Tool to read, parse 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
  -a, --onlyAppend             Only append new values, without updating existing 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)
  parse [options]              Parses and returns env file as JSON
```

### Read prop from file

```bash
$ 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
```

Also accept `-o` flag.

### Parse .env file/input as JSON

```bash
$ dotenv-tool parse -h
```

```
Usage: dotenv-tool parse [options]

Parses and returns env file as JSON

Options:
  -f, --file <filePath>  Input file to parse (if not given, stdio is used)
  -n, --normalize        Normalize keys in JSON (lowercase them)
  -h, --help             display help for command
```

Parse also accepts `-b` and `-o` flags.

## 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`.

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

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

```ts
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:

```ts
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
    noUpdate?: boolean;            // if true, only new values will be appended, but existing one wont be updated
    modifyMode?: ModifyMode;       // decide if new keys should or should not be added, and where. Default: ModifyMode.APPEND
};
```