Metadata-Version: 2.4
Name: envlit
Version: 0.0.2
Summary: A minimal CLI tool to organize, load, and switch between your project's environment contexts.
Author: Chaofan Luo
Project-URL: Homepage, https://luocfprime.github.io/envlit/
Project-URL: Repository, https://github.com/luocfprime/envlit
Project-URL: Documentation, https://luocfprime.github.io/envlit/
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: types-pyyaml>=6.0.12.20250915; extra == "dev"
Requires-Dist: pytest>=7.2.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: coverage>=7.13.4; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Requires-Dist: tox-uv>=1.11.3; extra == "dev"
Requires-Dist: mypy>=0.991; extra == "dev"
Requires-Dist: ruff>=0.9.2; extra == "dev"
Requires-Dist: mkdocs>=1.4.2; extra == "dev"
Requires-Dist: mkdocs-material>=8.5.10; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.26.1; extra == "dev"
Requires-Dist: mkdocs-static-i18n[material]>=1.3.0; extra == "dev"
Requires-Dist: mkdocs-macros-plugin>=1.3.9; extra == "dev"
Requires-Dist: tomlkit>=0.13.3; extra == "dev"
Dynamic: license-file

# envlit

[![CI](https://github.com/luocfprime/envlit/actions/workflows/ci.yml/badge.svg)](https://github.com/luocfprime/envlit/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/luocfprime/envlit/branch/main/graph/badge.svg)](https://codecov.io/gh/luocfprime/envlit)
[![Python Versions](https://img.shields.io/pypi/pyversions/envlit)](https://pypi.org/project/envlit/)
[![PyPI](https://img.shields.io/pypi/v/envlit)](https://pypi.org/project/envlit/)

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

## Installation

```bash
pip install envlit
```

## Quick Start

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

```bash
eval "$(envlit init)"
```

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

```yaml
env:
  PROJECT_MODE: "Development"
  DEBUG: "true"
```

Load and unload environment variables:

```bash
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

## Comparison with Similar Tools

| Feature | envlit | direnv | dotenv |
|---------|--------|--------|--------|
| **Auto-activation on cd** | ❌ | ✅ | ❌ |
| **Manual load/unload** | ✅ | ❌ | ✅ |
| **State restoration** | ✅ Full restore | ⚠️ Basic | ❌ No |
| **Config format** | YAML | Shell/direnvrc | `.env` |
| **Dynamic CLI flags** | ✅ | ❌ | ❌ |
| **PATH operations** | ✅ | ✅ | ❌ |
| **Lifecycle hooks** | ✅ 4 stages | ⚠️ Limited | ❌ |
| **Config inheritance** | ✅ | ❌ | ❌ |
| **Manual change detection** | ✅ | ❌ | ❌ |

**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

## Documentation

Visit [luocfprime.github.io/envlit](https://luocfprime.github.io/envlit/) for full documentation.

## Development

```bash
# Install dependencies
make install

# Run tests
pytest
```

## License

MIT License - see [LICENSE](LICENSE) for details.
