envcheck

A small CLI that checks whether your machine is ready to work on a given project.

You drop an envcheck.toml in your project root listing what's required — a Python version, CLI tools, environment variables — and running envcheck tells you what's missing.

  Environment Check

✓ Python 3.13.7 meets the required version >=3.12.
✓ Required command 'git' is available.
✗ Required command 'docker' was not found.
✗ Required environment variable 'API_KEY' is missing.

Exit code 0 means everything passed. Exit code 1 means something's missing. Pipe-friendly.

✨ Features

• Checks the running Python version against a minimum requirement
• Verifies that CLI tools (git, node, docker, etc.) are on PATH
• Checks that required environment variables are set
• Color-coded output via rich
• If no config file is found, prompts you to create one interactively
• All config sections are optional — only checks what you list

🧠 How it works

flowchart LR
    A[envcheck.toml] --> B[config/loader.py]
    B --> C[core/runner.py]
    C --> D[checks/]
    D --> E[output/terminal.py]
    E --> F[Terminal]

The loader reads envcheck.toml, the runner dispatches to the three checkers (python, commands, environment), and the output layer prints the results. Each layer does one thing.

📁 Project structure

envcheck/
├── src/
│   └── envcheck/
│       ├── checks/
│       │   ├── commands.py       # shutil.which checks
│       │   ├── environment.py    # os.getenv checks
│       │   └── python.py         # sys.version_info check
│       ├── cli/
│       │   ├── commands.py       # main() entry point
│       │   └── prompts.py        # interactive config creation prompt
│       ├── config/
│       │   └── loader.py         # reads envcheck.toml via tomllib
│       ├── core/
│       │   ├── models.py         # CheckResult, ProjectConfig dataclasses
│       │   └── runner.py         # coordinates checks
│       ├── output/
│       │   ├── helper.py         # rich console wrappers
│       │   └── terminal.py       # renders CheckResult list
│       └── __main__.py
├── envcheck.toml                 # config for this repo itself
└── pyproject.toml

🚀 Installation

pip install envready

Or install from source:

git clone https://github.com/1cz1/envcheck.git
cd envcheck
pip install -e .

Dev extras (includes pytest):

pip install -e ".[dev]"

After installing, the envready command is available globally, or you can run it as a module:

python -m envcheck

⚙️ Configuration

Create an envcheck.toml in your project root:

[python]
version = ">=3.12"

[commands]
required = ["git", "node", "docker"]

[environment]
required = ["API_KEY", "DATABASE_URL"]

All three sections are optional. If a section is absent, those checks are skipped entirely.

If envcheck.toml doesn't exist when you run the command, you'll be prompted to create an empty one.

▶️ Usage

Run from the project root (where envcheck.toml lives):

envready

Or via the module:

python -m envcheck

Exit codes

🧪 Tests

pytest

The pythonpath and testpaths are configured in pyproject.toml, so no extra flags needed.

🤝 Contributing

This is an early-stage project. If you find a bug or want to add a new check type, open an issue or a PR. Keep new checkers consistent with the pattern in checks/ — they should return a CheckResult, not print or raise.

📄 License

MIT