fixenv

Fix and standardize your local dev environment

fixenv is a CLI tool that detects, diagnoses, and repairs common local development environment issues — mismatched Node versions, missing Python, Docker not running, stale dependencies, and more.

Installation

npm install -g @flaviengibs/fixenv
# or run without installing
npx @flaviengibs/fixenv

Requires Node.js ≥ 18.

Usage

fixenv is meant to be run from the root of a project you want to diagnose or fix — not from its own directory.

cd my-project/    # the project you want to repair
fixenv doctor     # inspect that project's environment
fixenv up         # fix and start it

Detectors look for files like .nvmrc, package.json, requirements.txt, and docker-compose.yml in the current working directory.

Commands

fixenv doctor

Diagnose your current environment. Checks Node.js, Python, Docker, and package managers (npm, pnpm, yarn).

$ fixenv doctor

  System Diagnosis

  ✓  node          v20.11.0   matches .nvmrc
  ✗  python        missing    not found in PATH
  ✓  docker        v24.0.5    daemon running
  ⚠  npm           v9.8.1     ok
  ✓  pnpm          v8.15.0    ok

  Issues Found:

  python  →  Install Python 3: https://www.python.org/downloads/

When issues are found, each one is listed with a suggested fix. Run fixenv up to attempt automatic remediation.

fixenv up

Fix detected issues and start your environment end-to-end.

fixenv up

What it does:

• Runs all detectors in parallel
• Auto-fixes Node.js version mismatches via nvm (if available)
• Auto-fixes Python version mismatches via pyenv (if available)
• Installs Node and Python dependencies
• Starts Docker Compose services if a docker-compose.yml is present

If a version manager isn't installed, fixenv up prints the manual steps needed instead of failing silently.

fixenv sync

Check for environment drift and reinstall only what's needed.

fixenv sync

• Runs all detectors and reports any drift (version mismatches, missing tools)
• Reinstalls Node modules if package.json is newer than node_modules
• Reinstalls Python deps if requirements.txt or pyproject.toml is present

fixenv init

Generate a fixenv.yaml config file based on your current environment.

fixenv init

Detects your current Node and Python versions, Docker Compose services, and the right install command for your package manager (npm / yarn / pnpm). Writes the result to fixenv.yaml in the current directory.

Configuration (fixenv.yaml)

All fields are optional. fixenv works without a config file, but having one lets you pin versions and customize install commands.

runtime:
  node: "20.11.0"
  python: "3.11.0"

services:
  - web
  - db

install:
  node: "pnpm install"
  python: "pip install -r requirements.txt"

Field	Description
runtime.node	Required Node.js version. Matched against .nvmrc if present.
runtime.python	Required Python version.
services	Docker Compose services to start with fixenv up. Defaults to all services.
install.node	Command used to install Node dependencies.
install.python	Command used to install Python dependencies.

Auto-fix support

Tool	Version fix	How
Node.js	✓	nvm install + nvm use
Python	✓	pyenv install + pyenv local
Docker	—	Prints manual instructions
Package managers	—	Prints manual instructions

Development

npm install
npm run dev -- doctor   # run a command locally via tsx
npm run build           # compile to dist/
npm run typecheck       # type-check without emitting

License

MIT