execenv

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:

Installation

With pipx

As a cli application, it is recommended to install execenv via pipx:

pipx install execenv

To enable rich output, use

pipx install execenv[rich]

With pip

Alternatively, you can install execenv via pip:

pip install execenv

# Or with rich output
pip install execenv[rich]

From Source

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 install

After that, you can run the application with:

poetry run execenv

Usage

This 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.

Basic Usage

-e / --env

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=VAL

-f / --file

Or 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=VAL

-c / --clear

By 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 

-a / --append-env & --append-separator

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.test

Shell Related

-s / --shell

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 VAL

-C / --cwd

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)

Miscellaneous

-h / --help

Use -h / --help to get help information:

execenv -h

# Or simply without any flags and arguments
execenv

-V / --version

Use -V / --version to get the version information.

-v / -vv / --verbose

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.

--config

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.

Auto Completion

Click Built-in Shells (Bash 4.4+, Zsh & Fish)

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.

Other Shells

A completion utility execenv-completion will also be installed with execenv. You can use it to generate completion scripts for other shells:

Clink (Windows cmd)

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.

Contributing

Pull Requests are welcome!

It is strongly recommended to follow the Conventional Commits specification when writing commit messages and creating pull requests.

License

MIT