shdotenv

dotenv support for shell and POSIX-compliant .env syntax specification.

Storing configuration in the environment is one of the tenets of a twelve-factor app. Anything that is likely to change between deployment environments–such as resource handles for databases or credentials for external services–should be extracted from the code into environment variables.

The goals of this project

Provide language-independent CLI utilities
Provide a library that can safely load .env file from shell scripts
Define POSIX shell compatible .env syntax specification
Support for .env syntax dialects for interoperation

Requirements

shdotenv is a single file shell script with embedded awk script.

POSIX shell (dash, bash, ksh, zsh, etc)
awk (gawk, nawk, mawk, busybox awk)

Install

Download shdotenv (shell script) from releases.

$ wget https://github.com/ko1nksm/shdotenv/releases/download/[TAG]/shdotenv -O $HOME/bin/shdotenv
$ chmod +x $HOME/bin/shdotenv

Build your own

Requires shfmt.

$ git clone https://github.com/ko1nksm/shdotenv.git
$ cd shdotenv
$ make
$ make install PREFIX=$HOME

How to use

Usage

Usage: shdotenv [OPTION]... [--] [COMMAND [ARG]...]

  -d, --dialect DIALECT  Specify the .env dialect [default: posix]
                           (posix, ruby, node, python, php, go, rust, docker)
  -s, --shell SHELL      Output in the specified shell format [default: posix]
                           (posix, fish)
  -e, --env ENV_PATH     Location of the .env file [default: .env]
                           Multiple -e options are allowed
  -o, --overload         Overload predefined environment variables
  -n, --noexport         Do not export keys without export prefix
  -g, --grep PATTERN     Output only those that match the regexp pattern
  -k, --keyonly          Output only variable names
  -q, --quiet            Suppress all output
  -v, --version          Show the version and exit
  -h, --help             Show this message and exit

Use as CLI utility

Set environment variables and execute the specified command.

shdotenv [OPTION]... <COMMAND> [ARGUMENTS]...

Use as shell script library

Load the .env file into the shell script.

eval "$(shdotenv [OPTION]...)"

When run on the shell, it exports the environment variables to the current shell.

Additional CLI utility

contrib/dockerenv

The docker command has the --env-file option, but it only supports setting simple values.

docker cannot pass newlines from variables in --env-file files

This tool makes the files read by --env-file compatible with the .env format, and supports variable expansion and newlines.

Example: (Use dockerenv instead of docker)

dockerenv run --env-file .env -it debian

.env file syntax

# dotenv posix
# This line is a comment, The above line is a directive
COMMENT=The-#-sign-is-a-character # Spaces is required before the comment

UNQUOTED=value1 # Spaces and these characters are not allowed: !$&()*;<>?[\]`{|}~
SINGLE_QUOTED='value 2' # Single quotes cannot be used as value
DOUBLE_QUOTED="value 3" # Only these characters need to be \ escaped: $`"\

MULTILINE="line1
line2: \n is not a newline
line3"
LONGLINE="https://github.com/ko1nksm\
/shdotenv/blob/main/README.md"

ENDPOINT="http://${HOST}/api"

export EXPORT1="value"
export EXPORT2 # Equivalent to: export EXPORT2="${EXPORT2:-}"

The first line is a directive to distinguish between .env syntax dialects
Spaces before and after = are not allowed
Quoting is not required, but spaces and some symbols are not allowed
Single-quoted values cannot contains single quote in it
The following characters in double quoted values must be escaped with \: $ ` " \
No support for backslash escapes except for the above (i.e., \n is not a newline)
Variable expansion is only available if it is double-quoted
Bracing is required for variable expansion (Only ${VAR} is supported)

Detailed POSIX-compliant .env syntax specification

The formal .env syntax for this project is posix only. The posix is a subset of the POSIX shell and is compatible with shell scripts. Support for other .env syntax dialects is for interoperability purposes. Compatibility will be improved gradually, but is not fully compatible. Reports of problems are welcome.

docker: docker
ruby: dotenv
node: dotenv + dotenv-expand
python: python-dotenv
php: phpdotenv
go: godotenv
rust: dotenv

Comparing Dialects

Norcoen / shdotenv