works-on-my-machine

A tiny CLI that tells you why the repo works on someone else's machine but not yours.

__        _____  __  __ __  __
\ \      / / _ \|  \/  |  \/  |
 \ \ /\ / / | | | |\/| | |\/| |
  \ V  V /| |_| | |  | | |  | |
   \_/\_/  \___/|_|  |_|_|  |_|

works on my machine?
let's find out.

Features

• Detects Node, Vite, Docker, Python, Rust, .env, and Git project signals.
• Checks OS, current directory, Node, npm, pnpm, Yarn, Bun, Git, and Docker.
• Compares .env with .env.example.
• Detects occupied dev ports such as 3000, 5173, 8000, and 8080.
• Warns about Git dirty state, package manager lockfile mismatches, and Node version mismatches.
• Prints a clean terminal report or machine-readable JSON.
• Works on Linux, macOS, and Windows.

Installation

npm install -g works-on-my-machine

Usage

womm
womm doctor
womm --json
womm --verbose
womm --no-color
womm --ports 3000,5173,8080
womm version

Example Output

WORKS ON MY MACHINE REPORT

Project: my-app
Type: Node / Vite
OS: Linux 6.8.0 (x64)
Node: v20.12.2
Directory: /code/my-app

✓ package.json found
✓ pnpm installed 9.6.0
⚠ .env missing .env.example exists but .env is missing.
⚠ Port 5173 Port 5173 is already in use.
✗ Docker running Docker daemon is not reachable.

Likely problem:
.env missing: .env.example exists but .env is missing. Port 5173: Port 5173 is already in use. Docker running: Docker daemon is not reachable.

Suggested fixes:
cp .env.example .env
Stop the process using port 5173.
Start Docker and run womm again.

Supported Platforms

works-on-my-machine is built for normal terminals on:

• Linux
• macOS
• Windows PowerShell, Command Prompt, Windows Terminal, and Git Bash

Roadmap

• Detect common framework-specific required environment variables.
• Add optional process lookup for occupied ports.
• Add package manager install command suggestions.
• Add Docker Compose service health checks.
• Add plugin hooks for team-specific diagnostics.

Contributing

pnpm install
pnpm run dev
pnpm run lint
pnpm run test
pnpm run build

Keep checks small, readable, and safe when commands are missing. Cross-platform behavior matters: avoid Unix-only assumptions unless there is a Windows fallback.

License

MIT