EnvDoctor

Understand your development environment. Repair it with confidence.

EnvDoctor inspects installed tools, compares them with a project's requirements, and presents the results in a keyboard-driven terminal console. Diagnostics are read-only. Supported repairs show their exact commands and effects before you approve them.

Quick start

Requires Python 3.11+, Node.js 20+, and an interactive terminal. Windows is the primary supported platform; Windows Terminal is recommended.

From the repository directory:

.\run.cmd

The launcher creates a local Python environment, installs application dependencies, builds the TypeScript console, and starts EnvDoctor. It does not repair the inspected project automatically.

After setup, launch without reinstalling:

.\run.cmd -NoSetup
.\run.cmd -NoSetup -Project "C:\Projects\my-app"

Alternatively, run npm start -- "C:\Projects\my-app" after setup. ENVDOCTOR_PYTHON can select the Python interpreter used by the diagnostic engine.

The console

View	What it shows
Overview	Environment health and prioritized findings
Toolchains	Executable paths, versions, architectures, sources, and aliases
Requirements	Project dependencies and runtime compatibility
Issues	Errors, risks, evidence, and available repair previews
PATH & resolution	Search order, relevant variables, Windows SDKs, and policy
Compare	Portable profile compatibility and snapshot changes
Repair history	Approved commands, output, backups, and validation
Activity	Operations from the current console session

Scanning displays an animated pipeline with live diagnostic stages. Wide terminals use adjacent results and inspector panes; compact terminals place the inspector below the results.

Keyboard controls

Key	Action
1–8	Switch views
Tab	Change focus
Arrow keys, j / k	Select or scroll
Enter	Open details or activate a focused control
/, f, Esc	Search, cycle filters, clear filters or close an overlay
r, n, p	Rescan, check registry connectivity, choose a project
e, Shift+E	Export a JSON report or portable profile
c, b, s	Compare a profile, previous snapshot, or selected snapshot
a, u	Preview a repair or supported rollback
?	Open the keyboard reference
q, Ctrl+C	Exit after the current operation finishes

Diagnostics

Built-in detectors cover Python, Node.js, npm, Git, PowerShell, C/C++ compilers, CMake, Make, .NET, Java, Rust, Cargo, Go, Yarn, pnpm, pip, Pipenv, uv, and Poetry. Detection includes PATH candidates, Python launcher installations, project virtual environments, and supported Node version-manager locations.

Project analysis reads Python and Node manifests, version files, CMake configuration, Makefiles, and explicit EnvDoctor configuration. Discovery is limited to four directory levels and 300 manifests, excluding dependency and build directories.

Findings distinguish actual failures from informational inventory:

• Windows Python app execution aliases are labeled as aliases. They are not launched, assigned an invented interpreter version, or treated as failed installations.
• Python command aliases sharing the same interpreter environment are identified without counting them as separate installations.
• A .NET runtime installation is distinguished from a development SDK. Requiring dotnet as a tool requires an SDK.
• Multiple installations are informational; version requirements determine compatibility.
• Python build-system requirements are marked isolated rather than compared with unrelated packages in the project interpreter.
• Native libraries are located without running their initialization code. Transitive library loading is not verified.

Registry connectivity checks are optional and contact PyPI, npm, and GitHub. Dynamic setup.py files and project scripts are not executed during analysis. Unsupported dependency syntax and direct-URL provenance remain explicitly unverified.

Guided repairs

Repair	Scope
create-venv	Create a new project .venv; existing environments are preserved
pip-install	Install requirements.txt, or an editable pyproject.toml project, into .venv
npm-ci	Install from package-lock.json, replacing node_modules
npm-install	Install npm dependencies and create or update the lockfile
normalize-user-path	Remove duplicate and empty entries from Windows user PATH
clean-user-path	Also remove missing directories from Windows user PATH

Repair previews include the working directory, command, effects, backup files, and rollback instructions. Approval defaults to Cancel. The engine checks the preview again before execution, records approved changes in SQLite, and rescans afterward. npm lifecycle scripts are disabled in supported repairs.

PATH repairs preserve machine PATH and unresolved variable references. Review missing directories carefully: an offline or future installation may still need them. User PATH changes take effect in newly opened terminals. Automatic PATH rollback refuses to overwrite subsequent changes.

Package installations are not automatically reversible. Backed-up manifests and recorded output support manual recovery; newly created environments have explicit removal instructions. Installer selection, version switching, execution-policy changes, and machine PATH changes require manual remediation.

Command line

The installed Python entry point returns JSON. Global options precede the command:

.\.venv\Scripts\envdoctor.exe --project "C:\Projects\my-app" scan
.\.venv\Scripts\envdoctor.exe scan --connectivity --output report.json
.\.venv\Scripts\envdoctor.exe profile --output profile.json
.\.venv\Scripts\envdoctor.exe compare profile.json
.\.venv\Scripts\envdoctor.exe history
.\.venv\Scripts\envdoctor.exe diff 1 2
.\.venv\Scripts\envdoctor.exe repair pip-install

repair without --approve is a preview. To execute, pass the exact approval_token returned by that preview:

.\.venv\Scripts\envdoctor.exe repair pip-install --approve "<approval_token>"
.\.venv\Scripts\envdoctor.exe repairs
.\.venv\Scripts\envdoctor.exe rollback 1
.\.venv\Scripts\envdoctor.exe rollback 1 --approve

snapshot <id> reads a saved report. --data-dir <directory> changes the history location. Use --help on any command for its arguments.

Project configuration

Place envdoctor.json or envdoctor.toml at the project root. JSON example:

{
  "tools": {
    "python": ">=3.11,<3.14",
    "node": ">=20",
    "cmake": { "version": ">=3.25", "optional": true }
  },
  "environment": { "JAVA_HOME": "*" },
  "libraries": ["z"]
}

* requires an environment variable to be set; another value requires an exact match. Environment requirement values are redacted from reports, with exact matches represented by fingerprints. The PATH inspector includes selected development variables and local installation paths, so review exported reports before sharing them.

Storage and extension

On Windows, history and repair backups live under %LOCALAPPDATA%\EnvDoctor. Other systems default to ~/.local/share/EnvDoctor. SQLite stores snapshots and repair records; the Activity view is session-local.

Trusted Python packages can register a detector under the envdoctor.detectors entry-point group. Its class implements detect(project: pathlib.Path) -> list[envdoctor.model.Tool]. Detectors are loaded from the engine's Python environment.

Development

npm run check
npm run build
.\.venv\Scripts\python.exe -m compileall -q envdoctor
.\.venv\Scripts\python.exe -m pip check

The engine uses Python, the console uses TypeScript and Blessed, and Windows inspection uses PowerShell. Linux and macOS execution paths exist but have not received live verification comparable to Windows.