Home

Awesome

PS-Dotenv

Dotenv is a feature complete and straightforward direnv alternative for Powershell Core.

It also exposes the parser as a separate project you can use in other code.

Stability

Dotenv is stable and feature complete. the project is currently in maintain-only state. That means unless there's significant demand for a feature, only bug-fixes and other improvements will be added.

Features

Use Case

This module aims to provide the same functionality as direnv.

Add Update-Dotenv in your Prompt function and as you navigate directories, Dotenv will source the appropriate env files in the current directory and its parents.

Performance

The parsing of the env files is done in C# with a hand-written parser.

Dotenv, when there are env files under $PWD or its parents, adds about 1-10 milliseconds to the prompt, which itself takes about 5-20 milliseconds (on my machine). If no env files are detected, there's pretty much no overhead.

Installation

You have 3 options:

Via Scoop (recommended)

First add my bucket to scoop:

scoop bucket add insomnia https://github.com/insomnimus/scoop-bucket

Update scoop:

scoop update

Install the module:

scoop install ps-dotenv

Download a Release Archive

Simply download the latest release from the releases page.

Download Dotenv.zip, extract and put the Dotenv directory under your $PSModulePath as with any other module.

Build From Source

Make sure you have all the requirements installed:

To build the project, run the commands below.

git clone https://github.com/insomnimus/ps-dotenv
cd ps-dotenv
git checkout main # This is sometimes required.
./build.ps1 -release
# Now import the module.
Import-Module ./build/Dotenv

Usage

For the env files to be automatically sourced, you'll need to configure your prompt to let Dotenv know you possibly changed directories.

You don't need to check if the current directory changed or if there are files that must be loaded since Dotenv takes care of that for you by keeping its own state. If you don't have a powershell profile setup yet, please read this article from Microsoft first.

Important: Dotenv is disabled by default. You need to enable it with Enable-Dotenv in your powershell profile.

First, add this in your profile (don't forget to replace C:\example\dotenv with the actual path to the folder you built in above steps, or if Dotenv is in your module directory, replace the path with Dotenv):

Import-Module C:\example\dotenv
Enable-Dotenv # this is important, by default the module is disabled

Depending on if you have a custom prompt follow one of the following steps:

If you already have a customized prompt

You just have to add the following snippet inside your prompt function:

# We check if the command exists to not cause errors.
if(Test-Path function:/Update-Dotenv) { Dotenv\Update-Dotenv }

If you haven't customized your prompt

In your powershell profile, define a new prompt (the snippet below is the built-in prompt with dotenv enabled):

function prompt {
	# Print the built-in prompt:
	$(if (Test-Path variable:/PSDebugContext) { '[DBG]: ' }
		else { '' }) + 'PS ' + $(Get-Location) +
	$(if ($NestedPromptLevel -ge 1) { '>>' }) + '> '

	# We check if the command exists to not cause any errors.
	if(Test-Path function:/Update-Dotenv) { Dotenv\Update-Dotenv }
}

Documentation

Commands Overview