vault-env-loader 0.1.0__py3-none-any.whl

vault_env_loader-0.1.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: vault-env-loader
+Version: 0.1.0
+Summary: Load HashiCorp Vault KV secrets into environment variables before your app starts. Zero dependencies.
+Author: Kaylov H
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kaylovh/vault-env-loader/tree/main/python#readme
+Project-URL: Source, https://github.com/kaylovh/vault-env-loader
+Project-URL: Issues, https://github.com/kaylovh/vault-env-loader/issues
+Keywords: vault,hashicorp,secrets,env,environment,dotenv,kv,config
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# vault-env-loader (Python)
+
+Load secrets from HashiCorp Vault's KV engine into environment variables **before your application starts**. Your code keeps reading `os.environ` / `os.getenv` — Django settings, Flask config, pydantic `BaseSettings`, `django-environ`, `python-decouple` all keep working — and the `.env` file full of plaintext passwords can go.
+
+- **Zero dependencies.** One file, standard library only, Python ≥ 3.6. Old projects with pinned `requests` versions are not affected.
+- **Fails fast.** If a secret cannot be loaded, your application does not start (exit code 78), instead of failing later in business code.
+- **Imports like Spring Cloud Vault.** `vault://secret/my-app/prod/database`.
+- **The token stays out of your app.** `VAULT_TOKEN` is removed from the environment your application sees.
+- Works with HashiCorp Vault (KV v1 and v2, auto-detected) and with Vault-compatible servers.
+- Same configuration and behaviour as the [Node.js package](https://github.com/kaylovh/vault-env-loader/tree/main/node).
+
+## Quick start
+
+```bash
+pip install vault-env-loader
+```
+
+Configure it where you deploy (instead of putting secrets in `.env`):
+
+```bash
+VAULT_ADDR=https://vault.example.com
+VAULT_TOKEN=hvs.xxxxx                     # or VAULT_TOKEN_FILE=/run/secrets/vault-token
+VAULT_ENV_IMPORT="vault://secret/order-service/prod/database, vault://secret/order-service/prod/redis?prefix=REDIS_"
+```
+
+Then pick **one** way to hook it in.
+
+### A. Wrap the start command (recommended — no code change)
+
+```bash
+vault-env-loader -- gunicorn app.wsgi
+vault-env-loader -- uvicorn app.main:app --host 0.0.0.0
+vault-env-loader -- celery -A proj worker
+vault-env-loader -- python manage.py migrate
+python -m vault_env_loader -- python app.py      # when the scripts directory is not on PATH
+```
+
+```dockerfile
+ENTRYPOINT ["vault-env-loader", "--"]
+CMD ["gunicorn", "app.wsgi", "--bind", "0.0.0.0:8000"]
+```
+
+Works for anything: systemd, supervisor, cron, shell scripts — the wrapped program does not even have to be Python. On Linux and macOS the wrapper **replaces itself** with your command (`exec`): same PID, signals and exit code need no forwarding, and PID 1 in a container is your application.
+
+### B. One line at the top of your entry file
+
+```python
+import vault_env_loader; vault_env_loader.load()   # must run before anything reads the configuration
+```
+
+Where "the top" is:
+
+| Framework | Put it at the top of |
+|---|---|
+| Django | `manage.py`, `wsgi.py` and `asgi.py` (before `django` is imported), or the first line of `settings.py` |
+| Flask / FastAPI | the module that creates the app, before the config is read |
+| Celery | the module that creates the `Celery()` app |
+| python-dotenv | **before** `load_dotenv()` |
+
+`load()` blocks until every import is loaded, writes `os.environ`, removes `VAULT_TOKEN`, and returns the names it set. It does nothing if the environment was already loaded (for example by the wrapper, or in a reloader's child process).
+
+### C. Just get the values
+
+```python
+from vault_env_loader import fetch
+values = fetch()          # {'DB_PASSWORD': '...', ...}; os.environ is not touched
+```
+
+## Configuration
+
+Connection settings use Vault's standard variable names, so the `vault` CLI, `hvac` and other clients share them. Options of this tool start with `VAULT_ENV_`. Command-line flags of the same name take precedence.
+
+| Variable | Flag | Meaning |
+|---|---|---|
+| `VAULT_ADDR` | `--addr` | Vault address. Required. |
+| `VAULT_TOKEN` | — | Token. There is deliberately no `--token` flag: arguments are visible in `ps`. |
+| `VAULT_TOKEN_FILE` | `--token-file` | Read the token from a file instead. |
+| `VAULT_NAMESPACE` | — | Vault Enterprise namespace. |
+| `VAULT_CACERT` / `VAULT_CAPATH` | — | Extra CA certificate file / directory (every `*.pem` and `*.crt` in it). The system trust store is always used too. |
+| `VAULT_ENV_IMPORT` | `--import` | What to load, comma or newline separated (flag repeatable). Required. |
+| `VAULT_ENV_BASE` | `--base` | Base path for relative imports. |
+| `VAULT_ENV_OVERRIDE` | `--override` | `true`: replace variables that are already set. Default: keep them. |
+| `VAULT_ENV_KEEP_TOKEN` | `--keep-token` | `true`: leave `VAULT_TOKEN` in the application's environment. |
+| `VAULT_ENV_TIMEOUT` | `--timeout` | Seconds per request. Default 10. |
+| `VAULT_ENV_RETRIES` | `--retries` | Retries for transient failures. Default 3 (1 s, 2 s, 4 s). |
+| `VAULT_ENV_ALLOW_HTTP` | — | `true` to allow plain `http://` to a host other than localhost. Prints a warning on every start. |
+
+**TLS verification cannot be turned off.** If `VAULT_SKIP_VERIFY` is set, vault-env-loader stops with an error rather than silently ignoring it. Point `VAULT_CACERT` at your CA instead.
+
+**Proxies:** like every Python HTTP client, requests honour `HTTPS_PROXY` / `HTTP_PROXY` and `NO_PROXY`. Servers often set a global proxy for `pip`; if Vault is reachable directly, add its host to `NO_PROXY`. (The Node.js package does not use proxies.)
+
+If neither `VAULT_ADDR` nor `VAULT_ENV_IMPORT` is set, nothing is loaded and the command runs anyway — the same start command works on a laptop without Vault. Setting only some of them is an error.
+
+## Imports
+
+```
+[optional:]<location>[?prefix=<PREFIX>&name=auto|verbatim|upper&kv=1|2]
+
+location:  vault://<mount>/<path>    absolute, as in Spring Cloud Vault
+           <path>                    relative to the base path
+           vault://                  the base path itself
+```
+
+- **`optional:`** — skip the import if the path does not exist. Permission errors and outages still fail.
+- **`prefix=`** — prepend to every variable name from this import.
+- **`kv=`** — the KV engine version. Without it, vault-env-loader asks Vault (`sys/internal/ui/mounts`, like `vault kv get` does); the token's policy needs `read` on `sys/internal/ui/mounts/*` for that, otherwise version 2 is assumed.
+- When several imports set the same variable, **the later one wins** (with a warning).
+
+### Relative imports and the base path
+
+The base path is taken from, in order:
+
+1. `VAULT_ENV_BASE` (e.g. `secret/order-service/prod`);
+2. the token's metadata: if it has both `application` and `environment`, the base is `secret/<application>/<environment>`. Create such a token with `vault token create -policy=... -metadata=application=order-service -metadata=environment=prod`.
+
+With a token-derived base, every environment uses **the same** `VAULT_ENV_IMPORT="database, redis"` and only the token differs.
+
+## Variable names
+
+Vault keys may contain characters that are not valid in environment variable names (`db.password`, `spring.datasource.url`). The `name=` option decides:
+
+| `name=` | Rule | `DB_PASSWORD` | `db.password` | `spring.datasource.url` | `database_url` |
+|---|---|---|---|---|---|
+| `auto` (default) | Valid names unchanged; others upper-cased with invalid characters → `_` | `DB_PASSWORD` | `DB_PASSWORD` | `SPRING_DATASOURCE_URL` | `database_url` |
+| `verbatim` | Unchanged (`os.environ['db.password']` works; shells cannot use it) | `DB_PASSWORD` | `db.password` | `spring.datasource.url` | `database_url` |
+| `upper` | Always upper-cased, invalid characters → `_` | `DB_PASSWORD` | `DB_PASSWORD` | `SPRING_DATASOURCE_URL` | `DATABASE_URL` |
+
+If two keys of one import map to the same name (`db.password` and `db-password`), loading **fails** and names both keys — order never silently decides. On Windows, names are compared case-insensitively. Non-string values (Vault allows JSON) are injected as compact JSON text.
+
+## Precedence
+
+Variables that already exist in the environment **win** by default — the same rule as python-dotenv and Spring. That lets you override a value locally, and it means `load_dotenv()` called *after* vault-env-loader cannot overwrite Vault's values (unless you pass `override=True`), so a stale `.env` can stay in place until you have verified the migration. vault-env-loader prints the names (never the values) of variables it left alone. `VAULT_ENV_OVERRIDE=true` reverses this.
+
+## Checking a configuration
+
+```bash
+vault-env-loader check
+```
+
+prints the token's expiry and metadata, the path and version each import resolved to, and the variables that would be set — **names and lengths only, never values**.
+
+## Failures
+
+Nothing is started unless every non-optional import loads. The process exits with **78** (`EX_CONFIG`) and one line on stderr; `load()` and `fetch()` raise `VaultEnvError`.
+
+| Situation | Retried? |
+|---|---|
+| 401 / 403 — invalid, expired or revoked token, or the policy does not allow the path | no |
+| 404 — path does not exist (skipped if `optional:`) | no |
+| 429, 500, 502, 503, 504, connection errors, timeouts | yes, `VAULT_ENV_RETRIES` times — except a 502 that names keys with a permanent reason (e.g. `alias 'x' could not be resolved: not_found`), which fails at once |
+| 3xx redirects | not followed (the token would go with them); fails |
+
+A token that expires within 14 days produces a warning.
+
+## Things to know
+
+- **Rotation needs a restart.** Values are read once, at start — just like editing `.env`. `check` shows each path's version so you can tell whether a restart is due.
+- **gunicorn / uwsgi / celery** — with the wrapper, the master loads once and workers inherit the environment. With `load()`, put it where the master imports it (e.g. `gunicorn.conf.py`, or use `--preload`) so that workers do not each read Vault.
+- **Reloaders** (`runserver`, `uvicorn --reload`) start children with the loaded environment and `VAULT_ENV_LOADED`, so they do not read again. Restart the outer command to pick up new values.
+- **One value is limited to 128 KB** (the Linux limit for one environment string); larger values are refused with the key name.
+- **No `.pth` auto-loading.** Loading on every interpreter start (including `pip`) would be invisible and fragile; the wrapper already needs no code change.
+- **Windows** has no `exec`: the wrapper runs the command as a child and passes its exit code through.
+- Only token authentication for now; AppRole and Kubernetes auth may follow.
+
+## Library API
+
+```python
+from vault_env_loader import load, fetch, VaultEnvError
+
+load(env=None, **options)    # -> names set in os.environ (or in the mapping `env`)
+fetch(env=None, **options)   # -> {NAME: value}; does not touch the environment
+```
+
+`options` mirror the variables above: `addr`, `token`, `token_file`, `imports`, `base`, `namespace`, `cacert`, `capath`, `override`, `keep_token`, `timeout`, `retries`, `allow_http`. `env` is the mapping configuration is read from (and, for `load()`, written to); default `os.environ`. `VaultEnvError` has a `code`: `config`, `auth`, `not_found`, `resolve`, `collision`, `value`, `unavailable`. Messages contain paths and key names, never values or tokens.
+
+## Security notes
+
+- Secret values are never written to logs, error messages, argv or disk. Unexpected errors print only the exception type, never a traceback.
+- Redirects are not followed, so the token is only ever sent to `VAULT_ADDR`.
+- Requests carry `User-Agent: vault-env-loader/<version> python/<version>`, so server audit logs can tell which client read what.
+
+## License
+
+MIT

vault_env_loader-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+vault_env_loader.py,sha256=cFXWgQWOcGYIDgdcuAM3I2uWYg-QKlGlMVnDeTnwrYI,34206
+vault_env_loader-0.1.0.dist-info/licenses/LICENSE,sha256=zfIqtPxuRVI2pA6arKl_-G3qQU_8EorFucaFN1nKWK4,1065
+vault_env_loader-0.1.0.dist-info/METADATA,sha256=6ndazM4FmrpNnwjJ5Uq-DgD8wevkuVFEWeZH5RyDosU,12244
+vault_env_loader-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+vault_env_loader-0.1.0.dist-info/entry_points.txt,sha256=GZMjgaIVruI2SKxDmQe0aNDsd1-fmuBqUJIJEmITlG8,59
+vault_env_loader-0.1.0.dist-info/top_level.txt,sha256=30RFT_XrDSyywd5Ms1UuL1G1fZ4CiuKmPqpBw22dGAw,17
+vault_env_loader-0.1.0.dist-info/RECORD,,

vault_env_loader-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vault_env_loader-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vault-env-loader = vault_env_loader:_cli

vault_env_loader-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaylov H
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vault_env_loader-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vault_env_loader

vault_env_loader.py

@@ -0,0 +1,844 @@
+#!/usr/bin/env python3
+"""vault-env-loader: load HashiCorp Vault KV secrets into environment variables
+before your application starts.
+
+One file, zero dependencies, Python >= 3.6. It is at the same time:
+  - the CLI:     vault-env-loader [options] -- <command...>
+                 python -m vault_env_loader [options] -- <command...>
+  - the library: load() / fetch()
+
+Behaviour follows the Node.js package of the same name; both run the shared
+cases in spec/cases.json. Secret values never go to logs, error messages, argv
+or disk.
+"""
+
+import http.client
+import json
+import os
+import re
+import socket
+import ssl
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__version__ = '0.1.0'
+__all__ = ['load', 'fetch', 'VaultEnvError', '__version__']
+
+TAG = '[vault-env-loader]'
+EX_CONFIG = 78
+LOADED_MARK = 'VAULT_ENV_LOADED'
+TTL_WARN_SECONDS = 14 * 24 * 3600
+# Linux MAX_ARG_STRLEN: one "NAME=value\0" string handed to execve.
+MAX_ENV_STRING = 128 * 1024
+MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+VALID_ENV_NAME = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
+NAME_MODES = ('auto', 'verbatim', 'upper')
+# Some Vault-compatible servers that resolve keys from other stores answer 502
+# with "alias 'x' could not be resolved: <reason>" per failed key.
+TRANSIENT_ALIAS_REASONS = ('timeout', 'unavailable')
+ALIAS_FAILURE = re.compile(r"^alias '(.+)' could not be resolved: ([a-z_]+)$")
+TRUTHY = ('1', 'true', 'yes', 'on')
+FALSY = ('0', 'false', 'no', 'off')
+
+
+class VaultEnvError(Exception):
+    """A configuration or Vault error. Messages name paths and keys, never values or tokens."""
+
+    def __init__(self, message, code='error'):
+        super(VaultEnvError, self).__init__(message)
+        self.message = message
+        self.code = code
+
+
+def warn(message):
+    sys.stderr.write('%s %s\n' % (TAG, message))
+    sys.stderr.flush()
+
+
+def truthy(v):
+    return isinstance(v, str) and v.strip().lower() in TRUTHY
+
+
+def non_empty(v):
+    return v.strip() if isinstance(v, str) and v.strip() != '' else None
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+
+def read_config(options=None, env=None):
+    options = options or {}
+    env = os.environ if env is None else env
+
+    def pick(opt, *names):
+        if options.get(opt) is not None:
+            return options[opt]
+        for n in names:
+            if non_empty(env.get(n)) is not None:
+                return env[n]
+        return None
+
+    skip = non_empty(env.get('VAULT_SKIP_VERIFY'))
+    if skip is not None and skip.lower() not in FALSY:
+        raise VaultEnvError('VAULT_SKIP_VERIFY is set, but vault-env-loader never skips TLS verification. '
+                            'Unset it and point VAULT_CACERT at your CA instead.', 'config')
+
+    addr = non_empty(pick('addr', 'VAULT_ADDR'))
+    imports = pick('imports', 'VAULT_ENV_IMPORT')
+    if isinstance(imports, str):
+        imports = split_list(imports)
+    imports = [str(s).strip() for s in (imports or []) if str(s).strip()]
+
+    token_file = non_empty(pick('token_file', 'VAULT_TOKEN_FILE'))
+    token = options['token'] if options.get('token') is not None else non_empty(env.get('VAULT_TOKEN'))
+
+    if not addr and not imports:
+        return {'configured': False}
+
+    if not addr:
+        raise VaultEnvError('VAULT_ADDR is not set (VAULT_ENV_IMPORT is).', 'config')
+    if not imports:
+        raise VaultEnvError('VAULT_ENV_IMPORT is empty: name at least one path to load.', 'config')
+    if not token and token_file:
+        try:
+            with open(token_file, 'r', encoding='utf-8') as f:
+                token = f.read().strip()
+        except OSError as e:
+            raise VaultEnvError('Cannot read VAULT_TOKEN_FILE (%s): %s.' % (token_file, _errno_name(e)), 'config')
+        if not token:
+            raise VaultEnvError('VAULT_TOKEN_FILE (%s) is empty.' % token_file, 'config')
+    if not token:
+        raise VaultEnvError('No token: set VAULT_TOKEN or VAULT_TOKEN_FILE.', 'config')
+
+    url = urllib.parse.urlsplit(addr)
+    if url.scheme not in ('http', 'https') or not url.hostname:
+        if url.scheme and url.scheme not in ('http', 'https'):
+            raise VaultEnvError('VAULT_ADDR must start with https://', 'config')
+        raise VaultEnvError('VAULT_ADDR is not a valid URL.', 'config')
+    allow_http = bool(options['allow_http']) if options.get('allow_http') is not None else truthy(env.get('VAULT_ENV_ALLOW_HTTP'))
+    if url.scheme == 'http' and not is_loopback(url.hostname) and not allow_http:
+        raise VaultEnvError('VAULT_ADDR uses plain http to %s; use https, or set VAULT_ENV_ALLOW_HTTP=true '
+                            'if this network really has no TLS.' % url.hostname, 'config')
+
+    def num(v, default, name):
+        if v is None or v == '':
+            return default
+        try:
+            n = float(v)
+        except (TypeError, ValueError):
+            n = -1
+        if n != n or n < 0 or n == float('inf'):
+            raise VaultEnvError('%s must be a non-negative number.' % name, 'config')
+        return n
+
+    def flag(opt, var):
+        return bool(options[opt]) if options.get(opt) is not None else truthy(env.get(var))
+
+    return {
+        'configured': True,
+        'addr': addr.rstrip('/'),
+        'insecure_http': url.scheme == 'http' and not is_loopback(url.hostname),
+        'token': token,
+        'token_from_file': non_empty(env.get('VAULT_TOKEN')) is None and options.get('token') is None and bool(token_file),
+        'namespace': non_empty(pick('namespace', 'VAULT_NAMESPACE')),
+        'ssl_context': ssl_context(non_empty(pick('cacert', 'VAULT_CACERT')), non_empty(pick('capath', 'VAULT_CAPATH'))),
+        'imports': [parse_import(i) for i in imports],
+        'base': non_empty(pick('base', 'VAULT_ENV_BASE')),
+        'override': flag('override', 'VAULT_ENV_OVERRIDE'),
+        'keep_token': flag('keep_token', 'VAULT_ENV_KEEP_TOKEN'),
+        'timeout': num(pick('timeout', 'VAULT_ENV_TIMEOUT'), 10, 'VAULT_ENV_TIMEOUT'),
+        'retries': int(num(pick('retries', 'VAULT_ENV_RETRIES'), 3, 'VAULT_ENV_RETRIES')),
+        'retry_delay': options['retry_delay'] if options.get('retry_delay') is not None else 1.0,
+        'case_insensitive': bool(options['case_insensitive']) if options.get('case_insensitive') is not None else os.name == 'nt',
+    }
+
+
+def is_loopback(host):
+    return host in ('localhost', '127.0.0.1', '::1')
+
+
+def split_list(s):
+    return re.split(r'[,\n]', s)
+
+
+def _errno_name(e):
+    import errno
+    return errno.errorcode.get(getattr(e, 'errno', None) or 0, 'error')
+
+
+def ssl_context(cafile, capath):
+    """The system trust store plus VAULT_CACERT / every *.pem and *.crt in VAULT_CAPATH."""
+    ctx = ssl.create_default_context()
+    if cafile:
+        try:
+            ctx.load_verify_locations(cafile=cafile)
+        except (OSError, ssl.SSLError) as e:
+            raise VaultEnvError('Cannot read VAULT_CACERT (%s): %s.' % (cafile, _errno_name(e)), 'config')
+    if capath:
+        # OpenSSL's capath wants hashed file names; read the files ourselves, like the Node package.
+        try:
+            names = sorted(os.listdir(capath))
+        except OSError as e:
+            raise VaultEnvError('Cannot read VAULT_CAPATH (%s): %s.' % (capath, _errno_name(e)), 'config')
+        for n in names:
+            if re.search(r'\.(pem|crt)$', n, re.I):
+                try:
+                    with open(os.path.join(capath, n), 'r', encoding='utf-8') as f:
+                        ctx.load_verify_locations(cadata=f.read())
+                except (OSError, ssl.SSLError, ValueError):
+                    raise VaultEnvError('Cannot load certificate %s from VAULT_CAPATH.' % n, 'config')
+    return ctx
+
+
+# ---------------------------------------------------------------------------
+# Imports:  [optional:]location[?prefix=..&name=auto|verbatim|upper&kv=1|2]
+#   vault://<mount>/<path>   absolute (same as Spring Cloud Vault)
+#   vault://                 the base path itself
+#   <path>                   relative to the base path
+
+def parse_import(raw):
+    spec = raw.strip()
+    optional = False
+    if spec.startswith('optional:'):
+        optional = True
+        spec = spec[len('optional:'):].strip()
+    query = ''
+    q = spec.find('?')
+    if q >= 0:
+        query = spec[q + 1:]
+        spec = spec[:q]
+    prefix, name, kv = '', 'auto', None
+    for part in query.split('&') if query else []:
+        if not part:
+            continue
+        k, _, v = part.partition('=')
+        k, v = urllib.parse.unquote(k), urllib.parse.unquote(v)
+        if k == 'prefix':
+            prefix = v
+        elif k == 'name':
+            if v not in NAME_MODES:
+                raise VaultEnvError('Import "%s": name must be one of %s.' % (raw, ', '.join(NAME_MODES)), 'config')
+            name = v
+        elif k == 'kv':
+            if v not in ('1', '2'):
+                raise VaultEnvError('Import "%s": kv must be 1 or 2.' % raw, 'config')
+            kv = int(v)
+        else:
+            raise VaultEnvError('Import "%s": unknown option "%s" (known: prefix, name, kv).' % (raw, k), 'config')
+    if name != 'verbatim' and not re.match(r'^[A-Za-z0-9_]*$', prefix):
+        raise VaultEnvError('Import "%s": prefix may only contain letters, digits and _.' % raw, 'config')
+
+    if spec in ('vault://', 'vault:'):
+        kind, p = 'base', ''
+    elif spec.startswith('vault://'):
+        kind, p = 'absolute', spec[len('vault://'):]
+    elif '://' in spec:
+        raise VaultEnvError('Import "%s": only vault:// locations are supported.' % raw, 'config')
+    else:
+        kind, p = 'relative', spec
+    p = p.strip('/')
+    if kind != 'base' and not p:
+        raise VaultEnvError('Import "%s": empty path.' % raw, 'config')
+    if p and any(s in ('', '.', '..') for s in p.split('/')):
+        raise VaultEnvError('Import "%s": path segments may not be empty, "." or "..".' % raw, 'config')
+    if kind == 'absolute' and '/' not in p:
+        raise VaultEnvError('Import "%s": expected vault://<mount>/<path>.' % raw, 'config')
+    return {'raw': raw, 'optional': optional, 'kind': kind, 'path': p, 'prefix': prefix, 'name': name, 'kv': kv}
+
+
+# ---------------------------------------------------------------------------
+# HTTP
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # urllib would follow a 3xx and send X-Vault-Token to wherever it points.
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class _NetworkError(Exception):
+    def __init__(self, what):
+        super(_NetworkError, self).__init__(what)
+        self.what = what
+
+
+def encode_path(p):
+    return '/'.join(urllib.parse.quote(s, safe='') for s in p.split('/'))
+
+
+def _opener(cfg):
+    if '_opener' not in cfg:
+        # Proxies come from HTTPS_PROXY / HTTP_PROXY / NO_PROXY, as everywhere in Python.
+        cfg['_opener'] = urllib.request.build_opener(
+            _NoRedirect(), urllib.request.HTTPSHandler(context=cfg['ssl_context']))
+    return cfg['_opener']
+
+
+def http_get(cfg, api_path):
+    """GET <addr>/v1/<api_path> -> (status, parsed JSON body or None). Raises _NetworkError."""
+    headers = {
+        'X-Vault-Token': cfg['token'],
+        'X-Vault-Request': 'true',
+        'User-Agent': 'vault-env-loader/%s python/%s' % (__version__, '.'.join(map(str, sys.version_info[:3]))),
+        'Accept': 'application/json',
+    }
+    if cfg.get('namespace'):
+        headers['X-Vault-Namespace'] = cfg['namespace']
+    req = urllib.request.Request('%s/v1/%s' % (cfg['addr'], api_path), headers=headers, method='GET')
+    try:
+        resp = _opener(cfg).open(req, timeout=cfg['timeout'])
+    except urllib.error.HTTPError as e:
+        resp = e
+    except socket.timeout:
+        raise _NetworkError('timed out')
+    except urllib.error.URLError as e:
+        reason = e.reason
+        if isinstance(reason, socket.timeout):
+            raise _NetworkError('timed out')
+        if isinstance(reason, ssl.SSLError):
+            raise _NetworkError('failed (TLS: %s)' % (getattr(reason, 'reason', None) or 'certificate verification failed'))
+        raise _NetworkError('failed (%s)' % (_errno_name(reason) if isinstance(reason, OSError) else 'network error'))
+    except (OSError, ValueError, http.client.HTTPException) as e:
+        raise _NetworkError('failed (%s)' % (_errno_name(e) if isinstance(e, OSError) else type(e).__name__))
+    try:
+        status = resp.getcode()
+        try:
+            data = resp.read(MAX_RESPONSE_BYTES + 1)
+        except socket.timeout:
+            raise _NetworkError('timed out')
+        except OSError as e:
+            raise _NetworkError('failed (%s)' % _errno_name(e))
+        except http.client.HTTPException as e:
+            raise _NetworkError('failed (%s)' % type(e).__name__)
+        if len(data) > MAX_RESPONSE_BYTES:
+            raise _NetworkError('failed (response too large)')
+    finally:
+        resp.close()
+    try:
+        body = json.loads(data.decode('utf-8')) if data else None
+    except ValueError:
+        body = None
+    return status, body
+
+
+def alias_failures(body):
+    errors = body.get('errors') if isinstance(body, dict) else None
+    out = []
+    for e in errors if isinstance(errors, list) else []:
+        m = ALIAS_FAILURE.match(str(e))
+        if m:
+            out.append({'alias': m.group(1), 'reason': m.group(2)})
+    return out
+
+
+def retryable(status, body):
+    if status in (429, 500, 503, 504):
+        return True
+    if status == 502:
+        failures = alias_failures(body)
+        return not failures or all(f['reason'] in TRANSIENT_ALIAS_REASONS for f in failures)
+    return False
+
+
+def get_with_retry(cfg, api_path):
+    """GET with retries on transient failures; returns the final (status, body)."""
+    attempt = 0
+    while True:
+        res, net_err = None, None
+        try:
+            res = http_get(cfg, api_path)
+        except _NetworkError as e:
+            net_err = e
+        if res is not None and not retryable(*res):
+            return res
+        if attempt >= cfg['retries']:
+            if res is not None:
+                return res
+            hint = '' if net_err.what == 'timed out' else _proxy_hint(cfg)
+            raise VaultEnvError('Request to Vault %s.%s' % (net_err.what, hint), 'unavailable')
+        time.sleep(cfg['retry_delay'] * (2 ** attempt))
+        attempt += 1
+
+
+def _proxy_hint(cfg):
+    host = urllib.parse.urlsplit(cfg['addr']).hostname
+    proxies = urllib.request.getproxies()
+    scheme = urllib.parse.urlsplit(cfg['addr']).scheme
+    if proxies.get(scheme) and not urllib.request.proxy_bypass(host):
+        return ' The request went through the proxy in %s_PROXY; add %s to NO_PROXY if Vault is reachable directly.' % (scheme.upper(), host)
+    return ''
+
+
+# ---------------------------------------------------------------------------
+# Vault reads
+
+def lookup_self(cfg):
+    status, body = get_with_retry(cfg, 'auth/token/lookup-self')
+    if status in (401, 403):
+        return {'denied': True, 'ttl': 0, 'meta': {}}
+    if status != 200 or not isinstance(body, dict) or not isinstance(body.get('data'), dict):
+        return None
+    d = body['data']
+    ttl = d.get('ttl')
+    meta = d.get('meta')
+    return {
+        'denied': False,
+        'ttl': ttl if isinstance(ttl, (int, float)) and not isinstance(ttl, bool) else 0,
+        'meta': meta if isinstance(meta, dict) else {},
+    }
+
+
+def resolve_base(cfg, me):
+    if cfg.get('base'):
+        return {'base': cfg['base'].strip('/'), 'source': 'VAULT_ENV_BASE'}
+    m = me and me.get('meta') or {}
+    app, env = non_empty(m.get('application')), non_empty(m.get('environment'))
+    if app and env:
+        return {'base': 'secret/%s/%s' % (m['application'], m['environment']), 'source': 'token metadata',
+                'app': m['application'], 'env': m['environment']}
+    return {'base': None, 'source': None, 'denied': bool(me and me.get('denied'))}
+
+
+def full_path(imp, base_info):
+    if imp['kind'] == 'absolute':
+        if base_info.get('source') == 'token metadata':
+            seg = imp['path'].split('/') + ['', '']
+            if seg[0] == 'secret' and (seg[1] != base_info['app'] or seg[2] != base_info['env']):
+                raise VaultEnvError(
+                    'Import "%s" points at %s/%s, but this token belongs to %s/%s. A token can only read its own '
+                    'application and environment.' % (imp['raw'], seg[1] or '?', seg[2] or '?',
+                                                      base_info['app'], base_info['env']), 'config')
+        return imp['path']
+    if not base_info.get('base'):
+        if base_info.get('denied'):
+            raise VaultEnvError(
+                'Import "%s" is relative, and Vault refused to describe the token (permission denied on '
+                'auth/token/lookup-self): the token is invalid, expired or revoked, its IP is not allowed, or its '
+                'policy lacks lookup-self. Set VAULT_ENV_BASE or write vault://<mount>/<path> if the policy is '
+                'intended.' % imp['raw'], 'auth')
+        raise VaultEnvError('Import "%s" is relative, but there is no base path: set VAULT_ENV_BASE or write '
+                            'vault://<mount>/<path>.' % imp['raw'], 'config')
+    return base_info['base'] if imp['kind'] == 'base' else '%s/%s' % (base_info['base'], imp['path'])
+
+
+def locate(cfg, imp, p):
+    """Learn the mount and KV version the way `vault kv get` does."""
+    first = p.split('/')[0]
+    fallback = {'mount': first, 'rest': p[len(first) + 1:], 'kv': imp['kv'] or 2, 'probed': False}
+    if imp['kv']:
+        return fallback
+    status, body = get_with_retry(cfg, 'sys/internal/ui/mounts/%s' % encode_path(p))
+    d = body.get('data') if status == 200 and isinstance(body, dict) else None
+    if not isinstance(d, dict):
+        return fallback
+    mount = d['path'].rstrip('/') if isinstance(d.get('path'), str) and d['path'] else first
+    if p != mount and not p.startswith(mount + '/'):
+        return fallback
+    options = d.get('options') if isinstance(d.get('options'), dict) else {}
+    if str(options.get('version')) == '2':
+        version = 2
+    elif d.get('type') in ('kv', 'generic'):
+        version = 1
+    else:
+        version = 2
+    return {'mount': mount, 'rest': p[len(mount) + 1:], 'kv': version, 'probed': True}
+
+
+def describe_status(status, body, imp, p, loc):
+    where = '"%s" (%s)' % (imp['raw'], p)
+    if status in (401, 403):
+        return VaultEnvError('Permission denied reading %s: the token is invalid, expired or revoked, its IP is not '
+                             'allowed, or its policy does not allow reading this path.' % where, 'auth')
+    if status == 404:
+        other = 1 if loc['kv'] == 2 else 2
+        hint = '' if loc['probed'] else ' If this is a KV version %d mount, add ?kv=%d.' % (other, other)
+        return VaultEnvError('Not found: %s.%s' % (where, hint), 'not_found')
+    failures = alias_failures(body) if status == 502 else []
+    if failures:
+        listed = ', '.join('%s (%s)' % (f['alias'], f['reason']) for f in failures)
+        return VaultEnvError('Vault could not resolve %s: %s.' % (where, listed), 'resolve')
+    return VaultEnvError('Vault answered HTTP %s for %s.' % (status, where), 'unavailable')
+
+
+def read_import(cfg, imp, base_info):
+    p = full_path(imp, base_info)
+    loc = locate(cfg, imp, p)
+    if loc['kv'] == 2:
+        api_path = '%s/data/%s' % (encode_path(loc['mount']), encode_path(loc['rest']))
+    else:
+        api_path = encode_path(p)
+    status, body = get_with_retry(cfg, api_path)
+    if status == 200 and isinstance(body, dict) and isinstance(body.get('data'), dict):
+        outer = body['data']
+        data = outer.get('data') if loc['kv'] == 2 else outer
+        meta = outer.get('metadata') if loc['kv'] == 2 else None
+        version = meta.get('version') if isinstance(meta, dict) else None
+        if isinstance(data, dict):
+            return {'path': p, 'kv': loc['kv'], 'version': version, 'data': data}
+        # KV v2 answers 200 with data: null for a deleted latest version.
+        if loc['kv'] == 2:
+            return {'path': p, 'kv': loc['kv'], 'missing': True}
+    if status == 404 and imp['optional']:
+        return {'path': p, 'kv': loc['kv'], 'missing': True}
+    raise describe_status(status, body, imp, p, loc)
+
+
+# ---------------------------------------------------------------------------
+# Key -> environment variable names
+
+def env_name(key, mode):
+    if mode == 'verbatim':
+        return key
+    if mode == 'auto' and VALID_ENV_NAME.match(key):
+        return key
+    n = re.sub(r'[^A-Za-z0-9_]', '_', key).upper()
+    if re.match(r'^[0-9]', n):
+        n = '_' + n
+    return n
+
+
+def string_value(v):
+    if isinstance(v, str):
+        return v
+    if v is None:
+        return ''
+    if isinstance(v, float) and v.is_integer() and abs(v) < 1e21:
+        v = int(v)  # JSON has one number type: 1.0 is written 1, as in JavaScript
+    return json.dumps(v, separators=(',', ':'), ensure_ascii=False)
+
+
+def map_entries(data, imp, case_insensitive):
+    """One import's data -> [{key, name, value}]. Fails on collisions and on values an
+    environment cannot carry. Errors name keys, never values."""
+    entries = []
+    seen = {}
+    for key in data:
+        name = imp['prefix'] + env_name(key, imp['name'])
+        if not name or '=' in name or '\0' in name:
+            raise VaultEnvError('Key "%s" in "%s" cannot be used as an environment variable name; use ?name=auto '
+                                'or ?name=upper.' % (key, imp['raw']), 'value')
+        cmp = name.upper() if case_insensitive else name
+        if cmp in seen:
+            raise VaultEnvError('Keys "%s" and "%s" in "%s" both become %s. Rename one of them in Vault, or choose '
+                                'another ?name= mode.' % (seen[cmp], key, imp['raw'], name), 'collision')
+        seen[cmp] = key
+        value = string_value(data[key])
+        if '\0' in value:
+            raise VaultEnvError('The value of "%s" in "%s" contains a NUL byte, which an environment variable cannot '
+                                'hold.' % (key, imp['raw']), 'value')
+        if len(name.encode('utf-8')) + 1 + len(value.encode('utf-8', 'surrogatepass')) + 1 > MAX_ENV_STRING:
+            raise VaultEnvError('The value of "%s" in "%s" is larger than 128 KB, the limit for one environment '
+                                'variable.' % (key, imp['raw']), 'value')
+        entries.append({'key': key, 'name': name, 'value': value})
+    return entries
+
+
+def merge_imports(results, case_insensitive):
+    """Later imports win over earlier ones. Returns the merged values and the overridden names."""
+    values = {}
+    canonical = {}
+    overridden = []
+    for r in results:
+        for e in r.get('entries') or []:
+            cmp = e['name'].upper() if case_insensitive else e['name']
+            if cmp in canonical:
+                del values[canonical[cmp]]
+                if e['name'] not in overridden:
+                    overridden.append(e['name'])
+            canonical[cmp] = e['name']
+            values[e['name']] = e['value']
+    return {'values': values, 'overridden': overridden}
+
+
+def plan(values, env, override):
+    """Decide what to write into env. Existing variables win unless override."""
+    to_set = {}
+    kept = []
+    for name in values:
+        if not override and env.get(name) is not None:
+            kept.append(name)
+        else:
+            to_set[name] = values[name]
+    return {'set': to_set, 'kept': kept}
+
+
+# ---------------------------------------------------------------------------
+# Pipeline
+
+def collect(cfg):
+    warnings = []
+    if cfg['insecure_http']:
+        warnings.append('VAULT_ADDR uses plain http: the token and every secret cross the network unencrypted.')
+    me = lookup_self(cfg)
+    if me and not me['denied'] and 0 < me['ttl'] < TTL_WARN_SECONDS:
+        warnings.append('The token expires in %d day(s). Issue a new one before then.' % max(1, round(me['ttl'] / 86400.0)))
+    base_info = resolve_base(cfg, me)
+    results = []
+    for imp in cfg['imports']:
+        r = read_import(cfg, imp, base_info)
+        if r.get('missing'):
+            if not imp['optional']:
+                raise VaultEnvError('Not found: "%s" (%s).' % (imp['raw'], r['path']), 'not_found')
+            results.append({'raw': imp['raw'], 'path': r['path'], 'kv': r['kv'], 'skipped': True, 'entries': []})
+            continue
+        results.append({'raw': imp['raw'], 'path': r['path'], 'kv': r['kv'], 'version': r['version'],
+                        'entries': map_entries(r['data'], imp, cfg['case_insensitive'])})
+    merged = merge_imports(results, cfg['case_insensitive'])
+    if merged['overridden']:
+        warnings.append('Set by more than one import (the later one wins): %s.' % ', '.join(merged['overridden']))
+    return {'self': me, 'base_info': base_info, 'results': results, 'values': merged['values'], 'warnings': warnings}
+
+
+def apply(values, env, cfg):
+    p = plan(values, env, cfg['override'])
+    for name, value in p['set'].items():
+        env[name] = value
+    if p['kept']:
+        warn('Already set in the environment, kept as is (set VAULT_ENV_OVERRIDE=true to replace): %s.' % ', '.join(p['kept']))
+    env[LOADED_MARK] = '1'
+    if not cfg['keep_token']:
+        env.pop('VAULT_TOKEN', None)
+        if cfg['token_from_file']:
+            env.pop('VAULT_TOKEN_FILE', None)
+    return list(p['set'])
+
+
+NOT_CONFIGURED = 'VAULT_ADDR and VAULT_ENV_IMPORT are not set; nothing loaded from Vault.'
+
+
+# ---------------------------------------------------------------------------
+# Library API
+
+def fetch(env=None, **options):
+    """Read the configured imports and return {NAME: value} without touching the environment.
+
+    Keyword options mirror the environment variables: addr, token, token_file, imports, base,
+    namespace, cacert, capath, timeout, retries, allow_http.
+    """
+    cfg = read_config(options, os.environ if env is None else env)
+    if not cfg['configured']:
+        raise VaultEnvError(NOT_CONFIGURED, 'config')
+    result = collect(cfg)
+    for w in result['warnings']:
+        warn(w)
+    return result['values']
+
+
+def load(env=None, **options):
+    """Load into os.environ (or `env`). Returns the names that were set.
+
+    Call it before anything reads the configuration. Does nothing when VAULT_ENV_LOADED is
+    already set (for example by the vault-env-loader wrapper). Keyword options as for fetch(),
+    plus override and keep_token.
+    """
+    env = os.environ if env is None else env
+    if env.get(LOADED_MARK):
+        return []
+    cfg = read_config(options, env)
+    if not cfg['configured']:
+        warn(NOT_CONFIGURED)
+        return []
+    result = collect(cfg)
+    for w in result['warnings']:
+        warn(w)
+    return apply(result['values'], env, cfg)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+
+HELP = """vault-env-loader %s - load Vault KV secrets into environment variables, then run a command.
+
+Usage:
+  vault-env-loader [options] -- <command> [args...]
+  vault-env-loader check [options]      show what would be loaded (names only, never values)
+  vault-env-loader --version
+
+Options (each also has an environment variable):
+  --addr <url>          VAULT_ADDR
+  --token-file <path>   VAULT_TOKEN_FILE        (the token itself only via VAULT_TOKEN)
+  --import <spec>       VAULT_ENV_IMPORT        repeatable; comma-separated in the variable
+  --base <path>         VAULT_ENV_BASE          base for relative imports
+  --override            VAULT_ENV_OVERRIDE      replace variables that are already set
+  --keep-token          VAULT_ENV_KEEP_TOKEN    pass VAULT_TOKEN on to the command
+  --timeout <seconds>   VAULT_ENV_TIMEOUT       per request, default 10
+  --retries <n>         VAULT_ENV_RETRIES       default 3
+
+Import spec:  [optional:]vault://<mount>/<path> | <relative path> | vault://   [?prefix=X_&name=auto|verbatim|upper&kv=1|2]
+Docs: https://github.com/kaylovh/vault-env-loader
+""" % __version__
+
+
+def parse_args(argv):
+    opts = {}
+    imports = []
+    command = None
+    sub = None
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+
+        def val():
+            if i + 1 >= len(argv):
+                raise VaultEnvError('%s needs a value.' % a, 'config')
+            return argv[i + 1]
+
+        if a == '--':
+            command = argv[i + 1:]
+            break
+        elif a in ('--addr', '--token-file', '--import', '--base', '--timeout', '--retries'):
+            v = val()
+            i += 1
+            if a == '--import':
+                imports.extend(split_list(v))
+            else:
+                opts[a[2:].replace('-', '_')] = v
+        elif a == '--override':
+            opts['override'] = True
+        elif a == '--keep-token':
+            opts['keep_token'] = True
+        elif a == '--token':
+            raise VaultEnvError('There is no --token option: command-line arguments are visible to every user (ps). '
+                                'Use VAULT_TOKEN or --token-file.', 'config')
+        elif a == 'check' and sub is None:
+            sub = 'check'
+        elif a in ('--version', '-v'):
+            sub = 'version'
+        elif a in ('--help', '-h'):
+            sub = 'help'
+        elif not a.startswith('-') and sub is None:
+            # Allow "vault-env-loader gunicorn app:app" without "--".
+            command = argv[i:]
+            break
+        else:
+            raise VaultEnvError('Unknown option %s. See --help.' % a, 'config')
+        i += 1
+    if imports:
+        opts['imports'] = imports
+    return {'opts': opts, 'command': command, 'sub': sub}
+
+
+def check(opts):
+    cfg = read_config(opts, os.environ)
+    if not cfg['configured']:
+        sys.stdout.write(NOT_CONFIGURED + '\n')
+        return 0
+    result = collect(cfg)
+    me = result['self']
+    base_info = result['base_info']
+    lines = ['vault-env-loader %s' % __version__, 'addr     %s' % cfg['addr']]
+    if me and not me['denied']:
+        meta = ' '.join('%s=%s' % (k, v) for k, v in me['meta'].items())
+        expiry = 'expires in %dh' % round(me['ttl'] / 3600.0) if me['ttl'] else 'no expiry'
+        lines.append('token    %s%s' % (expiry, ', ' + meta if meta else ''))
+    else:
+        lines.append('token    (lookup-self not permitted)')
+    lines.append('base     %s' % ('%s (from %s)' % (base_info['base'], base_info['source']) if base_info.get('base') else '(none)'))
+    kept = plan(result['values'], os.environ, cfg['override'])['kept']
+
+    def canon(n):
+        return n.upper() if cfg['case_insensitive'] else n
+
+    last_import = {}
+    for i, r in enumerate(result['results']):
+        for e in r['entries']:
+            last_import[canon(e['name'])] = i
+    for i, r in enumerate(result['results']):
+        lines.append('')
+        version = ', version %s' % r['version'] if r.get('version') is not None else ''
+        skipped = '  [optional, not found: skipped]' if r.get('skipped') else ''
+        lines.append('import   %s  ->  %s  (kv v%s%s)%s' % (r['raw'], r['path'], r['kv'], version, skipped))
+        width = max([len(e['name']) for e in r['entries']] or [0])
+        for e in r['entries']:
+            notes = []
+            if e['name'] != e['key']:
+                notes.append('from %s' % e['key'])
+            if last_import.get(canon(e['name'])) != i:
+                notes.append('overridden by a later import')
+            elif e['name'] in kept:
+                notes.append('already set: kept')
+            lines.append('  %s  %5d chars%s' % (e['name'].ljust(width), len(e['value']), '  (%s)' % '; '.join(notes) if notes else ''))
+    for w in result['warnings']:
+        warn(w)
+    sys.stdout.write('\n'.join(lines) + '\n')
+    return 0
+
+
+def run(opts, command):
+    env = dict(os.environ)
+    if not env.get(LOADED_MARK):
+        cfg = read_config(opts, env)
+        if not cfg['configured']:
+            warn(NOT_CONFIGURED)
+        else:
+            result = collect(cfg)
+            for w in result['warnings']:
+                warn(w)
+            apply(result['values'], env, cfg)
+    return execute(command, env)
+
+
+def execute(command, env):
+    sys.stdout.flush()
+    sys.stderr.flush()
+    if os.name != 'nt':
+        # Replace this process: same PID, signals and exit status need no forwarding.
+        try:
+            os.execvpe(command[0], command, env)
+        except FileNotFoundError:
+            warn('Command not found: %s' % command[0])
+            return 127
+        except OSError as e:
+            warn('Could not start %s: %s' % (command[0], _errno_name(e)))
+            return 126
+    # Windows has no exec: run the command and pass its exit code through. Ctrl+C reaches
+    # the whole console group, so the child gets it too; we only wait for it.
+    try:
+        child = subprocess.Popen(command, env=env)
+    except FileNotFoundError:
+        warn('Command not found: %s' % command[0])
+        return 127
+    except OSError as e:
+        warn('Could not start %s: %s' % (command[0], _errno_name(e)))
+        return 126
+    while True:
+        try:
+            return child.wait()
+        except KeyboardInterrupt:
+            continue
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    try:
+        parsed = parse_args(argv)
+        if parsed['sub'] == 'version':
+            sys.stdout.write(__version__ + '\n')
+            return 0
+        if parsed['sub'] == 'help' or (not parsed['sub'] and not parsed['command']):
+            sys.stdout.write(HELP)
+            return 0 if parsed['sub'] == 'help' else 2
+        if parsed['sub'] == 'check':
+            return check(parsed['opts'])
+        if not parsed['command']:
+            raise VaultEnvError('No command given after --.', 'config')
+        return run(parsed['opts'], parsed['command'])
+    except VaultEnvError as e:
+        warn(e.message)
+        return EX_CONFIG
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:  # never print a traceback that could carry request data
+        warn('Unexpected error: %s' % type(e).__name__)
+        return EX_CONFIG
+
+
+def _cli():
+    sys.exit(main())
+
+
+if __name__ == '__main__':
+    _cli()