dev-env-doctor

dev-env-doctor is a small CLI that checks whether a developer machine is ready to work before a setup problem derails a coding session.

It is intentionally safe to run in public, shared, and automated environments:

• no secrets are printed
• no machine-specific files are uploaded
• warnings explain what to fix without changing your system by default
• JSON output is available for agents, scripts, and CI

Checks

The first release checks the basics that break local development most often:

• Git installation and identity
• GitHub SSH authentication
• GitHub CLI availability and authentication
• Python version and package tooling
• Node.js and npm
• Homebrew on macOS
• current Git repository cleanliness
• broken or duplicate PATH entries

Install

From a checkout:

python3 -m pip install .

For one-off local runs without installing:

python3 -m dev_env_doctor

Usage

Run every check:

dev-env-doctor

Run selected checks:

dev-env-doctor check git python github-ssh

List available checks:

dev-env-doctor --list

Machine-readable output:

dev-env-doctor --json

Make warnings fail automation:

dev-env-doctor --strict

Avoid network checks:

dev-env-doctor --no-network

Example Output

dev-env-doctor

OK    git          git version 2.50.1
OK    python       Python 3.14.4
WARN  github-cli   gh is not installed
SKIP  homebrew     Homebrew check only runs on macOS

Summary: 2 ok, 1 warn, 0 fail, 1 skip

Exit Codes

• 0: no failed checks
• 1: at least one failed check, or a warning when --strict is used
• 2: invalid CLI usage

Design Goals

This project is deliberately boring:

• standard-library runtime
• clear checks
• readable output
• easy tests
• no private assumptions

That makes it easy to extend. New checks live in src/dev_env_doctor/checks.py and return a CheckResult.

Development

Run tests:

PYTHONPATH=src python3 -m unittest discover -s tests

Run the CLI from source:

PYTHONPATH=src python3 -m dev_env_doctor --no-network