# dotenv: Loads environment variables from dotenv files

[ configuration, library, mit, program ] [ Propose Tags ]

In most applications, configuration should be separated from code. While it usually works well to keep configuration in the environment, there are cases where you may want to store configuration in a file outside of version control.

Dotenv files have become popular for storing configuration, especially in development and test environments. In Ruby, Python and Javascript there are libraries to facilitate loading of configuration options from configuration files. This library loads configuration to environment variables for programs written in Haskell.

To use, call loadFile from your application:

import Control.Monad (void)
import Configuration.Dotenv
void $loadFile defaultConfig This package also includes an executable that can be used to inspect the results of applying one or more Dotenv files to the environment, or for invoking your executables with an environment after one or more Dotenv files is applied. See the Github page for more information on this package. [Skip to Readme] Versions [RSS] [faq] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.3, 0.1.0.4, 0.1.0.5, 0.1.0.6, 0.1.0.7, 0.1.0.8, 0.1.0.9, 0.2.0.0, 0.3.0.0, 0.3.0.1, 0.3.0.2, 0.3.0.3, 0.3.1.0, 0.3.2.0, 0.3.3.0, 0.3.4.0, 0.4.0.0, 0.5.0.0, 0.5.0.1, 0.5.0.2, 0.5.1.0, 0.5.1.1, 0.5.2.0, 0.5.2.1, 0.5.2.2, 0.5.2.3, 0.5.2.4, 0.5.2.5, 0.6.0.1, 0.6.0.2, 0.6.0.3, 0.7.0.0, 0.8.0.0, 0.8.0.1, 0.8.0.2, 0.8.0.3, 0.8.0.4, 0.8.0.6, 0.8.0.7, 0.9.0.0 (info) CHANGELOG.md base (>=4.7 && <5.0), base-compat (>=0.4), containers, directory, dotenv, exceptions (>=0.8 && <0.11), megaparsec (>=7.0.1 && <8.0), optparse-applicative (>=0.11 && <0.15), process (>=1.6.3.0 && <1.7), text, transformers (>=0.4 && <0.6), void (==0.7.*), yaml (>=0.8) [details] MIT 2015-2017 Stack Builders Inc. Justin Leitgeb hackage@stackbuilders.com Configuration https://github.com/stackbuilders/dotenv-hs https://github.com/stackbuilders/dotenv-hs/issues head: git clone git@github.com:stackbuilders/dotenv-hs.git by camm at 2018-11-09T18:01:58Z LTSHaskell:0.8.0.7, NixOS:0.8.0.7, Stackage:0.9.0.0 dotenv 26052 total (80 in the last 30 days) (no votes yet) [estimated by Bayesian average] λ λ λ Docs available Last success reported on 2018-11-09 ## Modules [Index] [Quick Jump] ## Manual Flags NameDescriptionDefault dev Turn on development settings. Disabled Automatic Flags NameDescriptionDefault Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info ## Downloads #### Maintainer's Corner For package maintainers and hackage trustees Candidates ## Readme for dotenv-0.7.0.0 [back to package description] # Dotenv files for Haskell In most applications, configuration should be separated from code. While it usually works well to keep configuration in the environment, there are cases where you may want to store configuration in a file outside of version control. "Dotenv" files have become popular for storing configuration, especially in development and test environments. In Ruby, Python and Javascript there are libraries to facilitate loading of configuration options from configuration files. This library loads configuration to environment variables for programs written in Haskell. ## Installation In most cases you will just add dotenv to your cabal file. You can also install the library and executable by invoking stack install dotenv. ## Usage Set configuration variables in a file following the format below: S3_BUCKET=YOURS3BUCKET SECRET_KEY=YOURSECRETKEYGOESHERE  Then, calling Dotenv.load from your Haskell program reads the above settings into the environment: import Configuration.Dotenv (loadFile, defaultConfig) loadFile defaultConfig  After calling Dotenv.load, you are able to read the values set in your environment using standard functions from System.Environment such as lookupEnv and getEnv. ### NOTE: Empty environment variables If you need to have empty environment variables in your configuration, you can use something like the code below: fromMaybe "" <$> lookupEnv "ENV_VAR"


Currently, dotenv-hs doesn't allow you to set empty environment variables, because of setEnv from our System.Environment. This is bug reported in GHC ticket. We have had many dicussions about this. Fortunately, there is already some work for this issue in GHC Phabricator.

### Variable substitution

In order to use compound env vars use the following sintax within your env vars ${your_env_var}. For instance: DATABASE=postgres://${USER}@localhost/database


Running it on the CLI:

$dotenv "echo$DATABASE"


### Command substitution

In order to use the standard output of a command in your env vars use the following sintax $(your_command). For instance: DATABASE=postgres://$(whoami)@localhost/database


Running it on the CLI:

$dotenv "echo$DATABASE"


### Type checking envs

Env variables are simple strings. However, they can represent other types like integers, booleans, IP addresses, emails, URIs, and so on. We provide an interface that performs type checking after loading the envs and before running your application. If the type-check succeeded the application is executed, otherwise you will get an error with the types that mismatch.

In order to use this functionality you can use the loadSafeFile which takes the same configuration value as the loadFile function. Also, you need to have a .schema.yml in your current directory. This file must have the following structure:

- name: DOTENV
type: bool
required: true
- name: OTHERENV
type: bool
- name: PORT
type: integer
required: true
- name: TOKEN
type: text
required: false


It is a list of type and envs. So, in this example, DOTENV must have a value of true or false otherwise it won't be parsed as a boolean value. And envs like PORT must be any integer. Currently, we are supporting the following types:

• bool - Accepts values false or true
• integer - Accepts values of possitive integers
• text - Any text

require specifies if the env var is obligatory or not. In case you set it to true but do not provide it, you wil get an exception. When required is omited, the default value is false.

NOTE: All the variables which are required in the schema.yml must be defined in the dotenvs.

## Configuration

The first argument to loadFile specifies the configuration. You cans use defaultConfig which parses the .env file in your current directory and doesn't override your envs. You can also define your own configuration with the Config type.

False in configOverride means Dotenv will respect already-defined variables, and True means Dotenv will overwrite already-defined variables.

In the configPath you can write a list of all the dotenv files where are envs defined (e.g [".env", ".tokens", ".public_keys"]).

In the configExamplePath you can write a list of all the dotenv example files where you can specify which envs must be defined until running a program (e.g [".env.example", ".tokens.example", ".public_keys.example"]). If you don't need this functionality you can set configExamplePath to an empty list.

## Advanced Dotenv File Syntax

You can add comments to your Dotenv file, on separate lines or after values. Values can be wrapped in single or double quotes. Multi-line values can be specified by wrapping the value in double-quotes, and using the "\n" character to represent newlines.

The spec file is the best place to understand the nuances of Dotenv file parsing.

## Command-Line Usage

You can call dotenv from the command line in order to load settings from one or more dotenv file before invoking an executable:

$dotenv -f mydotenvfile myprogram  The -f flag is optional, by default it looks for the .env file in the current working directory. $ dotenv myprogram


Aditionally you can pass arguments and flags to the program passed to Dotenv:

$dotenv -f mydotenvfile myprogram -- --myflag myargument  or: $ dotenv -f mydotenvfile "myprogram --myflag myargument"


Also, you can use a --example flag to use dotenv-safe functionality so that you can have a list of strict envs that should be defined in the environment or in your dotenv files before the execution of your program. For instance:

$cat .env.example DOTENV= FOO= BAR=$ cat .env
DOTENV=123

$echo$FOO
123


This will fail:

$dotenv -f .env --example .env.example "myprogram --myflag myargument" > dotenv: Missing env vars! Please, check (this/these) var(s) (is/are) set: BAR  This will succeed: $ export BAR=123 # Or you can do something like: "echo 'BAR=123' >> .env"
$dotenv -f .env --example .env.example "myprogram --myflag myargument"  Hint: The env program in most Unix-like environments prints out the current environment settings. By invoking the program env in place of myprogram above you can see what the environment will look like after evaluating multiple Dotenv files. The --schema FILE will get the envs configuration from the FILE. For instance: $ cat .env
PORT=123a
$cat .schema.yml - name: PORT required: true type: integer  running dotenv will throw: $ dotenv -s .schema.yml "echo \$PORT"
dotenv: 1:4:
unexpected 'a'
expecting digit or end of input


NOTE: The flag can be omited when the .schema.yml is in the current working directory. To disable type checking add the flag --no-schema.

Justin Leitgeb