MIT licensed by Justin Leitgeb
Maintained by [email protected]
This version can be pinned in stack with:dotenv-0.12.0.0@sha256:2f25615cec37ff9a66a48ef0ebf2ac96ae989911d0c26c6796fc2f5247bdd665,4702

Module documentation for 0.12.0.0

Build StatusHackage

All Contributors

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.

Install

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 or you can download the dotenv binaries from our releases page.

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 or System.Environment.Blank (base >= 4.11.0.0), such as getEnv.

If your version of base is < 4.11.0.0, then setting an environment variable value to a blank string will remove the variable from the environment entirely.

Variable substitution

In order to use compound env vars use the following syntax within your env vars ${your_env_var}. For instance:

DATABASE=postgres://${USER}@localhost/database

Running it on the CLI:

$ dotenv "echo $DATABASE"
postgres://myusername@localhost/database

Command substitution

In order to use the standard output of a command in your env vars use the following syntax $(your_command). For instance:

DATABASE=postgres://$(whoami)@localhost/database

Running it on the CLI:

$ dotenv "echo $DATABASE"
postgres://myusername@localhost/database

Surrond with quotes

If your value starts with a character that produces a parse error (e.g. {) . Surround your value with quotes. You can also escape the quotes if they’re inside your value. For example:

JSON_SQ='{"a":[1,2,3], "b": "\'asdf\'"}'
JSON_DQ="{\"a\":[1,2,3], \"b\": \"'asdf'\"}"

Run it:

$ dotenv "echo $JSON_SQ" | jq .a
[
  1,
  2,
  3
]

Configuration

The first argument to loadFile specifies the configuration. You can 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.

A False in the configVerbose means that Dotenv will not print any message when loading the envs. A True means that Dotenv will print a message when a variable is loaded.

When configDryRyn is True, Dotenv will print out the loaded environment variables without executing the program.

A False on allowDuplicates means that Dotenv will not allow duplicate keys, and instead it will throw an error. A True means that Dotenv will allow duplicate keys, and it will use the last one defined in the file (default behavior).

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

Additionally, 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: The following variables are present in .env.example, but not set in the current environment, or .env: 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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT, see the LICENSE file.

Contributing

Do you want to contribute to this project? Please take a look at our contributing guideline to know how you can help us build it.


Check out our libraries | Join our team

Changes

MASTER

Dotenv 0.12.0.0

Modified

  • Ensure support from GHC 8.10 up to GHC 9.6

Possible breaking change

  • New attribute for Config data type to print env vars without actually running the command (kudos to @flandrade).

Dotenv 0.11.0.2

Modified

  • Allow optparse-applicative 0.18

Dotenv 0.11.0.1

Modified

  • Export internal module Configuration.Dotenv.Internal which exports all the internal modules.
  • Export configParser from Configuration.Dotenv.

Dotenv 0.11.0.0

Modified (Breaking change - new behavior)

  • Take last rather than first env var in dotenv file (reported by @rudymatela and solved by @anddriex). This will be the default behavior for the CLI, too.

Dotenv 0.10.1.0

Added

  • Short -x for --example flag

Modified

  • Fix union/unionBy bug, refactor .env.example check, and improve error message (Kudos to @pbrisbin)

Dotenv 0.10.0.1

Modified

  • Modify docs.

Dotenv 0.10.0.0

Modified

  • loadFile change return type (back to m ())

Dotenv 0.9.0.3

Added

  • Parse multi-word command interpolations (Kudos to @pbrisbin)

Dotenv 0.9.0.2

Added

  • Support for GHC = 9.0

Removed

  • Support for GHC < 8.6

Dotenv 0.9.0.1

Added

  • Allow optparse-applicative-0.17.0.0

Dotenv 0.9.0.0

  • Remove loadSafeFile. Users must create their own parsers to convert the read values from System.Environment to another data type. Therefore, loadSafeFile won’t be needed. We’ll remove this functionality to reduce dependencies.

Dotenv 0.8.1.0

  • Correct bounds for base. GHC support for versions older than 8.0 was dropped.

Dotenv 0.8.0.7

  • Allow megaparsec-0.9.0.0

Dotenv 0.8.0.6

  • Allow optparse-applicative-0.16.0.0

Dotenv 0.8.0.5

  • Extend ghc support to 8.8 and 8.10

Dotenv 0.8.0.4

  • Fix test fixtures

Dotenv 0.8.0.3

  • Add suppport for megaparsec-8.0.0

Dotenv 0.8.0.2

  • Add support for GHC 8.6

Dotenv 0.8.0.1

  • Support for optparse-applicative-0.15

Dotenv 0.8.0.0

  • Add Configuration.Dotenv.Environment module exporting functions from System.Environment, System.Environment.Compat, or System.Environment.Blank, depending on base version.
  • Add support for blank environment variables for base >= 4.11.0.0.

Dotenv 0.7.0.0

  • Hide helper modules in other-modules

Dotenv 0.6.0.3

  • Reexport defaultConfig in Configuration.Dotenv (thanks to: matsubara0507)

Dotenv 0.6.0.2

  • Support for process-1.6.3.0

Dotenv 0.6.0.1

  • Add support for megaparsec-7.0.1
  • Drop support for GHC 7.8.4

Dotenv 0.6.0.0

  • Move loadSafeFile to Configuration.Dotenv
  • Export Configuration.Dotenv.Types from Configuration.Dotenv
  • Change loadSafeFile signature to accept different types of validators.
  • Add type ValidatorMap = Map Text (Text -> Bool) for custom validations.

Dotenv 0.5.2.5

  • Update exceptions bounds >= 0.8 && < 0.11

Dotenv 0.5.2.4

  • Add error message when there is more than one definition in the Scheme for the same env

Dotenv 0.5.2.3

  • Update bounds exceptions == 0.9.*
  • Support megaparsec >= 6.4.0

Dotenv 0.5.2.1

  • Update documentation for Configuration.Dotenv.Types

Dotenv 0.5.2.0

  • Add loadSafeFile to typecheck the envs.
  • Add (--schema|-s) FILE flag to the dotenv CLI tool to enable safe mode.
  • Add (--no-schema) flag to the dotenv CLI tool to disable safe mode.
  • Turn safe mode on automatically when the .schema.yml file is present.
  • Make required optional in the .schema.yml.

Dotenv 0.5.1.1

  • Allow .env empty files

Dotenv 0.5.1.0

  • Add support for command substitution on env vars.

Dotenv 0.5.0.2

  • Set .env file as default file for environment variables.
  • Add --version flag to check the version of dotenv that is in use.

Dotenv 0.5.0.0

  • Add dotenv-safe functionality
  • Add the Config type with options to override env variables, and setting the path for .env and .env.example files.
  • Changed loadFile function to get Config with the paths for the .env file and the .env.example file.

Dotenv 0.4.0.0

  • Use Megaparsec 6.0
  • Dropped support for GHC 7.6

Dotenv 0.3.4.0

  • Allow optparse-applicative 0.14

Dotenv 0.3.3.0

  • Add support for variable expansion. Thanks to حبيب الامين (GitHub: habibalamin) for making this contribution.

Dotenv 0.3.2.0

  • Add the option to pass arguments to the program passed to Dotenv. Thanks to Oleg Grenrus (GitHub: phadej) for making this contribution.

Dotenv 0.3.1.0

  • Made interface more polymorphic so the functions works in any instance of MonadIO, not only IO. This should reduce amount of lifting in some cases.

  • Added onMissingFile helper to deal with possibly missing files.

  • Parser was rewritten to take full advantage of Megaparsec. hspec-megaparsec is now used for testing of the parser.

  • Dropped support for GHC 7.4.

Dotenv 0.3.0.3

  • Allow optparse-applicative 0.13

Dotenv 0.3.0.1

  • Remove unnecessary package dependencies.

Dotenv 0.3.0.0

  • Reverted change to Data.Text in favor of String, for maintaining compatibility with common Haskell system libraries. Added separate interface for parsing a file into tuples containing Data.Text values. Thanks to Daisuke Fujimura (GitHub: fujimura).
  • Fixed parsing of CRLF characters for Windows users.

Dotenv 0.2.0.0 (deprecated)

  • Changed public interfaces to use Data.Text.
  • Added function parseFile to read dotenv file without modifying the environment. Thanks to Daisuke Fujimura (GitHub: fujimura) for making this contribution.

Dotenv 0.1.0.0

  • First public release.