[](LICENSE)
[](https://pypi.org/project/execenv/)
[](https://pypi.org/project/execenv/)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](https://github.com/zyf722/execenv/actions/workflows/build.yml)
[](https://app.codecov.io/github/zyf722/execenv/)
# execenv
Powered by [`click`](https://click.palletsprojects.com/), `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`](https://github.com/ewels/rich-click), it also supports rich output for a better user experience:
## Installation
### With `pipx`
> [!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](https://pipx.pypa.io/stable/comparisons/) to gain more insights.
As a cli application, it is recommended to install `execenv` via [`pipx`](https://github.com/pypa/pipx):
```shell
pipx install execenv
```
To enable rich output, use
```shell
pipx install execenv[rich]
```
### With `pip`
Alternatively, you can install `execenv` via `pip`:
```shell
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`](https://python-poetry.org/) for dependency management. Make sure you have it installed before proceeding.
```shell
git clone https://github.com/zyf722/execenv.git
cd execenv/
poetry lock
poetry install
```
After that, you can run the application with:
```shell
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:
```shell
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](https://www.npmjs.com/package/dotenv#what-rules-does-the-parsing-engine-follow)) using the `-f` / `--file` flag:
```shell
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:
```shell
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` / `--clear` flags
> - Variables loaded from `.env` file with `-f` / `--file` flags
> - `-e` / `--env` flags
>
> 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.
#### `-a` / `--append-env` & `--append-separator`
Use `-a` / `--append-env` to append value to variables instead of overwriting:
```shell
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:
```shell
execenv --append-separator . -a KEY test -e KEY VAL -- execenv-echo KEY
# Output
# KEY=VAL.test
```
> [!WARNING]
> 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.
### 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:
```shell
# 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
```
> [!TIP]
> 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](https://docs.python.org/3/library/subprocess.html#security-considerations). 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`.
#### `-C` / `--cwd`
Use `-C` / `--cwd` to set the working directory, and note that `-s` / `--shell` is not mandatory to use this option:
```shell
# 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:
```shell
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:
```shell
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](#-f----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`](./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`](https://click.palletsprojects.com/en/8.1.x/shell-completion/), `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](https://github.com/chrisant996/clink).
You can install it by running:
```shell
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](https://chrisant996.github.io/clink/clink.html#completion-directories) of `clink` for more information.
## Contributing
[Pull Requests](https://github.com/zyf722/execenv/pulls) are welcome!
It is strongly recommended to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification when writing commit messages and creating pull requests.
## License
[MIT](./LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/zyf722/execenv",
"name": "execenv",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "cli, commandline, env, environment, environment variables",
"author": "MaxMixAlex",
"author_email": "MaxMixAlex@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/4e/ad8cc74571b74dfdbf9a71185bea55f4cf2442a32ac2ce2bb7df3a66ef2b/execenv-0.1.1.tar.gz",
"platform": null,
"description": "[](LICENSE)\n[](https://pypi.org/project/execenv/)\n[](https://pypi.org/project/execenv/)\n[](https://github.com/astral-sh/ruff)\n[](https://mypy-lang.org/)\n[](https://github.com/zyf722/execenv/actions/workflows/build.yml)\n[](https://app.codecov.io/github/zyf722/execenv/)\n\n# execenv\n\nPowered by [`click`](https://click.palletsprojects.com/), `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.\n\n\n\nThanks to [`rich-click`](https://github.com/ewels/rich-click), it also supports rich output for a better user experience:\n\n\n\n## Installation\n### With `pipx`\n> [!NOTE]\n> `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.\n>\n> Check out the [official documentation](https://pipx.pypa.io/stable/comparisons/) to gain more insights.\n\nAs a cli application, it is recommended to install `execenv` via [`pipx`](https://github.com/pypa/pipx):\n\n```shell\npipx install execenv\n```\n\nTo enable rich output, use\n\n```shell\npipx install execenv[rich]\n```\n\n### With `pip`\nAlternatively, you can install `execenv` via `pip`:\n\n```shell\npip install execenv\n\n# Or with rich output\npip install execenv[rich]\n```\n\n### From Source\nYou might also want to install `execenv` from source.\n\nThis project uses [`poetry`](https://python-poetry.org/) for dependency management. Make sure you have it installed before proceeding.\n\n```shell\ngit clone https://github.com/zyf722/execenv.git\ncd execenv/\n\npoetry lock\npoetry install\n```\n\nAfter that, you can run the application with:\n\n```shell\npoetry run execenv\n```\n\n## Usage\nThis package contains three cli applications:\n- `execenv`: The main application.\n- `execenv-completion`: A completion utility to generate completion scripts for other shells.\n- `execenv-echo`: A simple application for testing, which prints out K-V pairs of all given environment variables.\n\n### Basic Usage\n#### `-e` / `--env`\nTo run command with specific environment variables, you can pass them directly using the `-e` / `--env` flag:\n\n```shell\nexecenv -e SHELL overwritten -e KEY VAL -- execenv-echo SHELL KEY\n\n# Or put command before options\nexecenv execenv-echo SHELL KEY -e SHELL overwritten -e KEY VAL\n\n# Output\n# SHELL=overwritten\n# KEY=VAL\n```\n\n#### `-f` / `--file`\nOr you can load K-V pairs from a `.env` file ([dotenv compatible syntax](https://www.npmjs.com/package/dotenv#what-rules-does-the-parsing-engine-follow)) using the `-f` / `--file` flag:\n\n```shell\nexecenv -f .env -- execenv-echo KEY\n\n# Output\n# KEY=VAL\n```\n\n#### `-c` / `--clear`\nBy default, current environment variables will be preserved. You can override this behavior by using the `-c` / `--clear` flag:\n\n```shell\nexecenv -c -- set\n\n# Output differs on different platforms\n#\n# Note that for Windows with Python 3.10 and earlier,\n# this command might not work as expected with an error with `CreateProcess`\n# Check python/cpython#105436 for further information \n```\n\n> [!NOTE]\n> The apply order of environment variables is as follows:\n> \n> - Existing environment variables, if not cleared with `-c` / `--clear` flags\n> - Variables loaded from `.env` file with `-f` / `--file` flags\n> - `-e` / `--env` flags\n>\n> Variables with the same key will be overwritten by the latter ones.\n> \n> For those on the same level, the order of appearance in the command line will be followed.\n\n#### `-a` / `--append-env` & `--append-separator`\nUse `-a` / `--append-env` to append value to variables instead of overwriting:\n\n```shell\nexecenv -e KEY VAL -a KEY test -- execenv-echo KEY\n\n# Output\n# KEY=VAL;test (on Windows)\n# KEY=VAL:test (on Linux / macOS)\n\n# Also works with existing ones\nexecenv -a PATH test -- execenv-echo PATH\n\n# Output\n# PATH=%PATH%;test (on Windows)\n# PATH=$PATH:test (on Linux / macOS)\n```\n\nBy default `os.pathsep` is used as the separator when appending. You can change it by using `--append-separator` flag:\n\n```shell\nexecenv --append-separator . -a KEY test -e KEY VAL -- execenv-echo KEY\n\n# Output\n# KEY=VAL.test\n```\n\n> [!WARNING]\n> 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.\n\n### Shell Related\n#### `-s` / `--shell`\nUse `-s` / `--shell` to set `shell=True` to `subprocess` in order to use expansion, built-in commands, pipes, redirection and other shell features:\n\n```shell\n# Linux / macOS\nexecenv -e PATH overwritten -e KEY VAL -s -- echo EXECENV_PATH \\$KEY\n\n# Windows\nexecenv -e PATH overwritten -e KEY VAL -s -- echo EXECENV_PATH %KEY%\n\n# Output\n# overwritten VAL\n```\n\n> [!TIP]\n> 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`.\n>\n> 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.\n\n> [!WARNING]\n> You should be cautious when using `shell=True` as it might lead to [security vulnerabilities](https://docs.python.org/3/library/subprocess.html#security-considerations). Make sure you trust the input and the command you are running.\n>\n> 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`.\n\n#### `-C` / `--cwd`\nUse `-C` / `--cwd` to set the working directory, and note that `-s` / `--shell` is not mandatory to use this option:\n\n```shell\n# Linux / macOS\nexecenv -C /home -- pwd\n\n# Windows\nexecenv -C C:\\ -s -- echo EXECENV_CD\n\n# Output\n# C:\\ (on Windows)\n# /home (on Linux / macOS)\n```\n\n### Miscellaneous\n#### `-h` / `--help`\nUse `-h` / `--help` to get help information:\n\n```shell\nexecenv -h\n\n# Or simply without any flags and arguments\nexecenv\n```\n\n#### `-V` / `--version`\nUse `-V` / `--version` to get the version information.\n\n#### `-v` / `-vv` / `--verbose`\nUse `-v` / `-vv` / `--verbose` to enable verbose mode, which is useful for debugging:\n\n```shell\nexecenv -e SHELL overwritten -e KEY VAL -v -- execenv-echo SHELL KEY\n```\n\n\n\nA header section will be added to the output to show details about `execenv` itself. Use `-vv` to show more information.\n\n#### `--config`\nUse `--config` to load configuration from a file. Note that config file itself is [a valid `.env` file](#-f----file).\n\nDefault config file will be created after the first run at `~/.execenv.env` on Linux / macOS and `%USERPROFILE%\\.execenv.env` on Windows.\n\nRefer to [`execenv/config.py`](./execenv/config.py) to see all available configuration with their default values.\n\n### Auto Completion\n#### Click Built-in Shells (Bash 4.4+, Zsh & Fish)\nFor [shells supported by `click`](https://click.palletsprojects.com/en/8.1.x/shell-completion/), `execenv` will automatically setup tab completion after the first run (screenshot below is for Fish):\n\n\n\nYou may restart or source your shell to enable the completion.\n\n#### Other Shells\nA completion utility `execenv-completion` will also be installed with `execenv`. You can use it to generate completion scripts for other shells:\n\n\n\n##### Clink (Windows `cmd`)\n`execenv-completion` provides support for [clink](https://github.com/chrisant996/clink).\n\n\n\nYou can install it by running:\n\n```shell\nexecenv-completion -s clink [-p /path/to/your/script]\n```\n\nIt will create a `completions` directory in the specified path (or the current directory if not provided) with the completion `.lua` script inside.\n\n> [!NOTE]\n> Check out related [documentation](https://chrisant996.github.io/clink/clink.html#completion-directories) of `clink` for more information.\n\n## Contributing\n\n[Pull Requests](https://github.com/zyf722/execenv/pulls) are welcome!\n\nIt is strongly recommended to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification when writing commit messages and creating pull requests.\n\n## License\n[MIT](./LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Run command with a certain environment.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/zyf722/execenv",
"Repository": "https://github.com/zyf722/execenv"
},
"split_keywords": [
"cli",
" commandline",
" env",
" environment",
" environment variables"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31da4f22a9d0a6e6d085cf12f7dbde860b4a08a77db6665bcf060c1a753dff8c",
"md5": "76bdb009addce6ade6736a1393138eb5",
"sha256": "adf1f747dfa9067f62d023add9a913c3408b551ac85e24e141996ad3339cfbd1"
},
"downloads": -1,
"filename": "execenv-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76bdb009addce6ade6736a1393138eb5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 12026,
"upload_time": "2024-09-04T16:36:40",
"upload_time_iso_8601": "2024-09-04T16:36:40.283934Z",
"url": "https://files.pythonhosted.org/packages/31/da/4f22a9d0a6e6d085cf12f7dbde860b4a08a77db6665bcf060c1a753dff8c/execenv-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c4ead8cc74571b74dfdbf9a71185bea55f4cf2442a32ac2ce2bb7df3a66ef2b",
"md5": "a12c317ca6e99d16e2ab8293c46911fd",
"sha256": "6ef4d6f1c41f37cc0cc65732a175fa8f20800e91cb6e86e1d925d8b007e6f15f"
},
"downloads": -1,
"filename": "execenv-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "a12c317ca6e99d16e2ab8293c46911fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 13703,
"upload_time": "2024-09-04T16:36:42",
"upload_time_iso_8601": "2024-09-04T16:36:42.079450Z",
"url": "https://files.pythonhosted.org/packages/1c/4e/ad8cc74571b74dfdbf9a71185bea55f4cf2442a32ac2ce2bb7df3a66ef2b/execenv-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 16:36:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zyf722",
"github_project": "execenv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "execenv"
}
JSON
