Powered by click, execenv is a simple cross-platform cli utility that allows you to execute commands with different environment variables by passing directly or loading from a .env file.
Thanks to rich-click, it also supports rich output for a better user experience:
Note
pipx is a specialized package installer. It can only be used to install packages with cli entrypoints and help you to isolate the environment of each package.
Check out the official documentation to gain more insights.
As a cli application, it is recommended to install execenv via pipx:
pipx install execenvTo enable rich output, use
pipx install execenv[rich]Alternatively, you can install execenv via pip:
pip install execenv
# Or with rich output
pip install execenv[rich]You might also want to install execenv from source.
This project uses poetry for dependency management. Make sure you have it installed before proceeding.
git clone https://github.com/zyf722/execenv.git
cd execenv/
poetry lock
poetry installAfter that, you can run the application with:
poetry run execenvThis package contains three cli applications:
execenv: The main application.execenv-completion: A completion utility to generate completion scripts for other shells.execenv-echo: A simple application for testing, which prints out K-V pairs of all given environment variables.
To run command with specific environment variables, you can pass them directly using the -e / --env flag:
execenv -e SHELL overwritten -e KEY VAL -- execenv-echo SHELL KEY
# Or put command before options
execenv execenv-echo SHELL KEY -e SHELL overwritten -e KEY VAL
# Output
# SHELL=overwritten
# KEY=VALOr you can load K-V pairs from a .env file (dotenv compatible syntax) using the -f / --file flag:
execenv -f .env -- execenv-echo KEY
# Output
# KEY=VALBy default, current environment variables will be preserved. You can override this behavior by using the -c / --clear flag:
execenv -c -- set
# Output differs on different platforms
#
# Note that for Windows with Python 3.10 and earlier,
# this command might not work as expected with an error with `CreateProcess`
# Check python/cpython#105436 for further information Note
The apply order of environment variables is as follows:
- Existing environment variables, if not cleared with
-c/--clearflags - Variables loaded from
.envfile with-f/--fileflags -e/--envflags
Variables with the same key will be overwritten by the latter ones.
For those on the same level, the order of appearance in the command line will be followed.
Use -a / --append-env to append value to variables instead of overwriting:
execenv -e KEY VAL -a KEY test -- execenv-echo KEY
# Output
# KEY=VAL;test (on Windows)
# KEY=VAL:test (on Linux / macOS)
# Also works with existing ones
execenv -a PATH test -- execenv-echo PATH
# Output
# PATH=%PATH%;test (on Windows)
# PATH=$PATH:test (on Linux / macOS)By default os.pathsep is used as the separator when appending. You can change it by using --append-separator flag:
execenv --append-separator . -a KEY test -e KEY VAL -- execenv-echo KEY
# Output
# KEY=VAL.testWarning
Be cautious when setting the separator to special characters like | with -s / --shell flag, as they might be misinterpreted by the shell, or even lead to security vulnerabilities.
Use -s / --shell to set shell=True to subprocess in order to use expansion, built-in commands, pipes, redirection and other shell features:
# Linux / macOS
execenv -e PATH overwritten -e KEY VAL -s -- echo EXECENV_PATH \$KEY
# Windows
execenv -e PATH overwritten -e KEY VAL -s -- echo EXECENV_PATH %KEY%
# Output
# overwritten VALTip
You should escape $ on Linux / macOS using \ and % on Windows using ^ to prevent them from being expanded by the shell if you want to use new values set with execenv.
Alternatively, you can use a prefix to access them. By default, EXECENV_ is used as the prefix. You can change it by using --env-varref-prefix flag.
Warning
You should be cautious when using shell=True as it might lead to security vulnerabilities. Make sure you trust the input and the command you are running.
On POSIX platforms, due to features like expansion can not work with shlex.join as they are escaped for security reasons, internally subprocess.list2cmdline is used by default, which is less secure and compatible with POSIX. You can change it by using --shell-strict flag to switch back to shlex.join.
Use -C / --cwd to set the working directory, and note that -s / --shell is not mandatory to use this option:
# Linux / macOS
execenv -C /home -- pwd
# Windows
execenv -C C:\ -s -- echo EXECENV_CD
# Output
# C:\ (on Windows)
# /home (on Linux / macOS)Use -h / --help to get help information:
execenv -h
# Or simply without any flags and arguments
execenvUse -V / --version to get the version information.
Use -v / -vv / --verbose to enable verbose mode, which is useful for debugging:
execenv -e SHELL overwritten -e KEY VAL -v -- execenv-echo SHELL KEY
A header section will be added to the output to show details about execenv itself. Use -vv to show more information.
Use --config to load configuration from a file. Note that config file itself is a valid .env file.
Default config file will be created after the first run at ~/.execenv.env on Linux / macOS and %USERPROFILE%\.execenv.env on Windows.
Refer to execenv/config.py to see all available configuration with their default values.
For shells supported by click, execenv will automatically setup tab completion after the first run (screenshot below is for Fish):
You may restart or source your shell to enable the completion.
A completion utility execenv-completion will also be installed with execenv. You can use it to generate completion scripts for other shells:
execenv-completion provides support for clink.
You can install it by running:
execenv-completion -s clink [-p /path/to/your/script]It will create a completions directory in the specified path (or the current directory if not provided) with the completion .lua script inside.
Note
Check out related documentation of clink for more information.
Pull Requests are welcome!
It is strongly recommended to follow the Conventional Commits specification when writing commit messages and creating pull requests.