Enhancement: Command-line argument to load extra .env files

[smac89]

Summary

I have a situation where I would like to load multiple .env files when the application starts, but as it stands now, litestar does not provide such a feature.

So far, I've solved the problem for myself by creating a CLIPlugin:

from pathlib import Path
from typing import Any, override

from litestar.plugins import CLIPluginProtocol


class CLIPlugin(CLIPluginProtocol):
    """The purpose of this plugin is to add the --env-file option to the run command"""

    @override
    def on_cli_init(self, cli):
        from click import Option

        run_cmd = cli.commands.get("run")
        run_cmd.params.append(
            Option(
                ["--env-file", "env_files"], multiple=True, type=Path, help="Load environment variables from file(s)"
            )
        )

        original_callback = run_cmd.callback

        def wrapped_callback(*args: Any, env_files: tuple[Path] | None = (), **kwargs: Any):
            import dotenv

            for env_file in env_files:
                dotenv.load_dotenv(dotenv_path=env_file, override=True)
            return original_callback(*args, **kwargs)

        run_cmd.callback = wrapped_callback

However, I think it would be nice to have this feature as part of Litestar.

Basic Example

litestar run --env-file .env --env-file .env.prod

Drawbacks and Impact

No response

Unresolved questions

No response

[provinzkraut]

Right now we implicitly load the env from a .env file. This would mean changing that.

That's generally a change I'm in favour of, and I don't see any reason not to also support multiple env-files.

@smac89 Would you want to contribute your solution?

[smac89]

I wouldn't mind contributing, but following the contributing guide leads to the following error after running make install:

Resolved 319 packages in 2.64s
  × Failed to build `psycopg-c==3.2.9`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `cython_backend.build_wheel` failed (exit status: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      creating build/lib.linux-x86_64-cpython-313/psycopg_c
      copying psycopg_c/version.py -> build/lib.linux-x86_64-cpython-313/psycopg_c
      copying psycopg_c/_uuid.py -> build/lib.linux-x86_64-cpython-313/psycopg_c
      copying psycopg_c/__init__.py -> build/lib.linux-x86_64-cpython-313/psycopg_c
      copying psycopg_c/_psycopg.pyi -> build/lib.linux-x86_64-cpython-313/psycopg_c
      copying psycopg_c/py.typed -> build/lib.linux-x86_64-cpython-313/psycopg_c
      copying psycopg_c/pq.pxd -> build/lib.linux-x86_64-cpython-313/psycopg_c
      creating build/lib.linux-x86_64-cpython-313/psycopg_c/_psycopg
      copying psycopg_c/_psycopg/oids.pxd -> build/lib.linux-x86_64-cpython-313/psycopg_c/_psycopg
      copying psycopg_c/_psycopg/endian.pxd -> build/lib.linux-x86_64-cpython-313/psycopg_c/_psycopg
      copying psycopg_c/_psycopg/__init__.pxd -> build/lib.linux-x86_64-cpython-313/psycopg_c/_psycopg
      creating build/lib.linux-x86_64-cpython-313/psycopg_c/pq
      copying psycopg_c/pq/libpq.pxd -> build/lib.linux-x86_64-cpython-313/psycopg_c/pq
      copying psycopg_c/pq/__init__.pxd -> build/lib.linux-x86_64-cpython-313/psycopg_c/pq
      running build_ext

      [stderr]
      /home/chigozirim/.cache/uv/builds-v0/.tmpBH6kMw/lib/python3.13/site-packages/setuptools/dist.py:759:
      SetuptoolsDeprecationWarning: License classifiers are deprecated.
      !!

              ********************************************************************************
              Please consider removing the following classifiers in favor of a SPDX license expression:

              License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)

              See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for details.
              ********************************************************************************

      !!
        self._finalize_license_expression()
      couldn't run 'pg_config' --includedir: [Errno 2] No such file or directory: 'pg_config'
      error: [Errno 2] No such file or directory: 'pg_config'

      hint: This usually indicates a problem with the package or the build environment.
  help: `psycopg-c` (v3.2.9) was included because `litestar:dev` (v2.16.0) depends on `psycopg[c]` (v3.2.9) which
        depends on `psycopg-c`
make: *** [Makefile:32: install] Error 1

Will try again later. The changes are simple enough:

commands/core.py

...
@click.option("env_files", "--env-file", help="Load environment variables from file(s)", type=click.Path(), multiple=True, default=(".env",), envvar="LITESTAR_ENV_FILES")
def run_command(..., env_files: tuple[pathlib.Path], ctx: click.Context) -> None:
    for env_file in env_files:
        dotenv.load_dotenv(dotenv_path=env_file, override=True)
    ...

The only other dependency added is python-dotenv.

I'm actually wondering if this option shouldn't be added to the litestar command itself, so that the rest of the commands which depend on environment variables can use those variables 🤔

[sakosha]

Can I take this one?

[sakosha]

Related: #3217

[smac89]

Thanks, @sakosha