envlit

A simple CLI tool to organize, load, and switch between your project's environment variable contexts.

Installation

pip install envlit

Quick Start

Initialize envlit in your shell (add to .bashrc or .zshrc):

eval "$(envlit init)"

Create a config file at .envlit/default.yaml:

dotenv:
  - "./.env"
  - "./.env.local"

env:
  PROJECT_MODE: "Development"
  DEBUG: "true"

Dotenv paths are relative to the YAML file. Later dotenv files override earlier ones with a warning, and env: overrides dotenv values last. Declared files are required; envlit never auto-discovers .env files.

Load and unload environment variables:

el                       # Load default profile
echo $PROJECT_MODE       # Output: Development (variable set by envlit)
echo $DEBUG              # Output: true (variable set by envlit)

eul                      # Unload environment variables
echo $PROJECT_MODE       # Output: (empty - variable restored to original state)
echo $DEBUG              # Output: (empty - variable restored to original state)

Features

• Smart state tracking - Detects manual changes and preserves them
• Dynamic flags - YAML-defined flags become CLI options
• Path operations - Prepend, append, remove path entries
• Lifecycle hooks - Run scripts before/after load/unload
• Config inheritance - Extend base configurations
• Explicit dotenv imports - Load one or more .env files with deterministic precedence

Comparison with Similar Tools

Key Differences:

• envlit: Manual control with explicit load/unload. Full state tracking with restoration. Better for variable contexts that you want to toggle on demand.
• direnv: Automatically activates on directory change. Great for per-directory isolation but less control over when environments load. Basic restoration.
• dotenv: Simple .env file loading, no restoration or advanced features. Good for 12-factor apps but lacks state management.

When to use envlit:

• You want CLI flags that map to environment variables (especially useful for long names and values)
• You want explicit control over when environments load/unload
• You need to preserve user modifications and restore clean state
• You need complex PATH operations or lifecycle hooks

AI Agent Skill

Documentation

Visit luocfprime.github.io/envlit for full documentation.

Development

# Install dependencies
make install

# Run tests
pytest

License

MIT License - see LICENSE for details.