Installation

On macOS, you can brew install shadowenv or download the binary from GitHub and drop it somewhere on your path. If this build isn’t right for your architecture, the only other option for now is to build it manually from source.

Building from Source

Clone the git repo

dev clone shadowenv if you work at Shopify, or:

git clone https://github.com/Shopify/shadowenv
cd shadowenv

Install Rust

dev up if you work at Shopify, or:

# Install rustup
curl https://sh.rustup.rs -sSf | sh

# Install the version of rust that we need
rustup switch nightly-2018-12-26k

Build and Install

cargo build --release

This will generate an artifact at target/release/shadowenv. You can copy this wherever you like on your path, for example:

cp target/release/shadowenv /usr/local/bin/shadowenv

Add to your shell profile

Shadowenv relies on a shell hook to make changes when you change directories. In order to use it, add a line to your shell profile (.zshrc, .bash_profile, or config.fish) reading:

# (only add one of these!)
eval "$(shadowenv init bash)" # for bash
eval "$(shadowenv init zsh)"  # for zsh
shadowenv init fish | source  # for fish

Make sure to restart your shell after adding this.

A Quick Demo

Shadowenv constantly scans your current directory, and all of its parents, for a directory named .shadowenv.d. The nearest one wins, just like if you have nested git repositories.

When a .shadowenv.d directory is found, Shadowenv first checks that you’ve Trusted it. Then, it looks for any files ending with .lisp in that directory, and runs them as Shadowlisp.

Here’s an example of what a Shadowlisp file might look like:

(env/set "DEBUG" "1")
(env/prepend-to-pathlist "PATH" "./bin")

If you try creating an empty .shadowenv.d, and then adding that content to a *.lisp file inside it, you’ll get an error back about an “untrusted” shadowenv. In order to fix this, run:

shadowenv trust

This will mark the directory as trusted, telling shadowenv that it can safely run any shadowlisp programs it finds inside. You should see “shadowenv activated.” in your terminal. Then, if you echo $DEBUG, you will see “1” printed, because the script set “DEBUG” to “1”.

Next, cd .. to get out of the directory containing the shadowenv. You will see “deactivated shadowenv.” printed automatically. If you echo $DEBUG, you’ll see whatever value you had prior to creating the Shadowenv: most likely no value.

Those are the basics! There’s a bit more you can do with Shadowlisp, and we have some suggestions for how to actually use Shadowenv in an organization.

Add to your editor or IDE

Depending on you use your editor, you may find it helpful to have the same environment variable settings as in your shell. We have plugins for most common editors, and writing new plugins is relatively straightforward.

Check out the Integration page for more information and a list of available plugins.

Usage in Scripts

Sometimes you may want a Shadowenv loaded in a non-interactive script. This is what shadowenv exec is for. When you run shadowenv exec, Shadowenv will load the Shadowlisp from the current directory and execute the specified program. For example, imagine a directory with a Shadowenv that puts nginx on the PATH:

#!/bin/sh
cd /path/to/thing/with/dot-shadowenv

shadowenv exec -- nginx -g 'daemon off;'

In this case, we didn’t need to load the Shadowenv shell hook, as shadowenv exec loaded the environment before executing nginx.