Why conflint?

Most "works on my machine" disasters are configuration disasters:

• A teammate deleted a key from .env that your code still requires.
• The CI workflow never defines DATABASE_URL, so the app crashes at deploy, not at commit.
• DB_HOST vs DBHOST — the typo that no linter catches because your linter doesn't read your code.
• A real API key sitting in a committed .env.

.env linters validate a file against a schema you write by hand. conflint reads the actual source code to learn the truth about what your app needs, then reconciles it against every place that value should exist.

Quick start

pip install conflint

# From your project root:
confl check                  # lint the whole project
confl sync                   # regenerate an accurate .env.example
confl explain DB_HOST        # who reads DB_HOST? where is it defined?

Example output:

conflint  checked 42 files (173 config reads, 58 definitions) in 1.24s

app/main.py
  CL001 error: 'DATABASE_URL' is read in code but not defined in any configuration source:12
    hint: Add it to your .env (then run `confl sync` to refresh .env.example)
  CL003 warning: 'DBHOST' is undefined but resembles 'DB_HOST' (distance 1):45
    hint: Did you mean 'DB_HOST'?
docker-compose.yml
  CL004 error: 'POSTGRES_PASSWORD' looks like a committed secret

42 files checked - 2 errors, 1 warning, 0 infos

Commands

Rules

What gets scanned

Configuration sources (all gitignore-aware in reverse)

Configuration

Config is optional. When you need it, use conflint.toml (or pyproject.toml under [tool.conflint]):

[tool.conflint]
fail-level = "error"              # error | warning | info
require-example = true            # enforce a populated .env.example

enable = { CL003 = "error" }      # raise a rule's severity
disable = ["CL002"]               # turn rules off

ignore-names = ["CI=true", "NODE_ENV=*"]
ignore-paths = ["scripts/**", "vendor/**"]

sources = ["dotenv", "docker-compose", "github-actions", "kubernetes", "terraform"]
scanners = ["python", "javascript"]
reporters = ["text"]

Run confl init to write a commented template.

CI integration

GitHub Actions

- name: Lint configuration
  uses: conflint/conflint@v1
  with:
    reporter: github          # inline PR annotations
    fail-level: error

or with pip directly:

- uses: actions/setup-python@v5
  with: { python-version: "3.12" }
- run: pip install conflint
- run: confl check --github

pre-commit

- repo: https://github.com/conflint/conflint
  rev: v0.1.0
  hooks:
    - id: conflint

Output formats

confl check                       # rich terminal output
confl check --json                # stable JSON schema (v1.0)
confl check --sarif               # SARIF 2.1.0 (CodeQL, Azure Pipelines, GitLab)
confl check --github              # GitHub Actions workflow commands
confl check --report junit        # JUnit XML for Jenkins dashboards
confl check --json --output report.json   # write to a file

Development

git clone https://github.com/conflint/conflint
cd conflint
pip install -e ".[dev]"
pytest
ruff check .
mypy src

License

MIT. See LICENSE.

Similar tools & why conflint is different