Metadata-Version: 2.4
Name: dotenv-lint
Version: 1.0.0
Summary: Validate .env files against a schema with secret strength checking
Project-URL: Homepage, https://github.com/FaraiMacheka/envguard
Project-URL: Repository, https://github.com/FaraiMacheka/envguard
Project-URL: Issues, https://github.com/FaraiMacheka/envguard/issues
Project-URL: Changelog, https://github.com/FaraiMacheka/envguard/blob/main/CHANGELOG.md
Author-email: Farai Macheka <farai.m.macheka@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ci,configuration,dotenv,env,secrets,validation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# envguard

Validate `.env` files against a schema, with secret-strength heuristics, drift
detection between environments, and a CI-friendly CLI. Zero runtime
dependencies — pure Python 3.8+.

## Install

```bash
pip install dotenv-lint
# dev tools
pip install -e .[dev]
```

> The PyPI distribution is named **`dotenv-lint`** because `envguard`
> and similar variants were taken / blocked by PyPI's name-similarity
> filter. The import name (`envguard`) and CLI command (`envguard`)
> are unchanged.

## Quick start

Declare a schema in `.env.schema.toml`:

```toml
[DATABASE_URL]
type     = "url"
required = true

[PORT]
type     = "int"
required = true
range    = [1024, 65535]

[JWT_SECRET]
type        = "str"
required    = true
secret      = true
min_length  = 32
```

Validate from the CLI:

```bash
envguard validate .env --schema .env.schema.toml
envguard validate .env --schema .env.schema.toml --format json
envguard validate .env --schema .env.schema.toml --strict --exit-on-fail
envguard secrets .env
envguard compare .env.development .env.production
envguard scaffold .env > .env.schema.toml
```

Or from Python:

```python
from envguard import validate

result = validate(env_file=".env", schema=".env.schema.toml")
if not result.is_valid:
    for err in result.errors:
        print(err.code, err.message)
    raise SystemExit(1)
```

## Exit codes

| Code | Meaning                            |
|------|------------------------------------|
| 0    | All checks passed                  |
| 1    | One or more errors found           |
| 2    | One or more warnings (no errors)   |
| 3    | File not found or unreadable       |

## Schema format

TOML is the primary format (`.env.schema.toml`); JSON is also accepted
(`.env.schema.json`). The built-in TOML reader is a constrained subset
sufficient for the schema layout — top-level tables containing scalars,
booleans, and single-line arrays. If you need richer TOML syntax, switch to
JSON.

Supported types: `str`, `int`, `float`, `bool`, `url`, `email`, `list`,
`json`, `path`, `uuid`. Constraints per key: `required`, `default`,
`description`, `secret`, `choices`, `range`, `schemes` (URLs), `min_length`,
`max_length`, `must_exist` (paths).

## Secret strength

When `secret = true`, EnvGuard runs five heuristics: minimum-length,
Shannon-entropy, blocklist, sequential/repeated/keyboard-walk patterns, and
all-same-case. Findings come back as `WEAK_SECRET` /
`PLAINTEXT_SECRET_PATTERN` warnings with HIGH/MEDIUM/LOW severity.

## Pre-commit hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/FaraiMacheka/envguard
    rev: v1.0.0
    hooks:
      - id: envguard
        args: [".env", "--schema", ".env.schema.toml", "--exit-on-fail"]
```

The hook calls `envguard validate` with the args you supply, so point it
at whichever `.env` and schema your repo uses.

## Security

For vulnerability reports, see [SECURITY.md](SECURITY.md).

## License

MIT.