Skip to main content

​
Prerequisites

Before installing bdg, ensure you have the following:

Node.js

Version 20.0.0 or higher required

npm/yarn/pnpm

Package manager of your choice

Chrome

Google Chrome or Chromium installed

Platform

macOS, Linux, or Windows (WSL only)
Node.js requirement: bdg requires Node.js 20.0.0 or higher. Check your version with node --version.

​
Install bdg

Choose your preferred package manager: 
npm install -g browser-debugger-cli@alpha
Currently installing from the @alpha tag. This will change to stable once v1.0 is released.

​
Verify Installation

Confirm bdg is installed correctly: 
bdg --help
You should see the command reference with available commands and options. Check the installed version: 
bdg --version

​
Platform Support

​
Supported Platforms

✅ Fully supportedbdg works out of the box on macOS. Chrome will be automatically located in standard installation paths.
✅ Fully supportedWorks on all major distributions. Ensure Chrome or Chromium is installed:
# Debian/Ubuntu
sudo apt install chromium-browser

# Fedora/RHEL
sudo dnf install chromium

# Arch
sudo pacman -S chromium
✅ Supported via WSLRun bdg in Windows Subsystem for Linux (WSL 2 recommended):
  1. Install WSL: Follow Microsoft’s WSL installation guide
  2. Install Node.js in WSL
  3. Install Chrome for Linux in WSL
  4. Install bdg using npm/yarn/pnpm
❌ Not yet supportedPowerShell and Git Bash are not currently supported. Use WSL as a workaround.

​
Troubleshooting

​
Command not found

If you get command not found: bdg after installation:
1

Check npm global path

Ensure npm’s global bin directory is in your PATH:
npm config get prefix
Add <prefix>/bin to your PATH if missing.
2

Verify installation

Check if the package is installed globally:
npm list -g browser-debugger-cli
3

Reinstall if needed

Try reinstalling with verbose output:
npm install -g browser-debugger-cli@alpha --verbose

​
Node.js version mismatch

If you see an error about Node.js version: 
Error: The engine "node" is incompatible with this module.
Solution: Upgrade Node.js to version 20.0.0 or higher: 
# Using nvm (recommended)
nvm install 20
nvm use 20

​
Chrome not found

If bdg can’t locate Chrome: 
Error: Chrome not found
Ensure Chrome is installed in the standard location:
ls -la /Applications/Google\ Chrome.app
If Chrome is elsewhere, bdg will attempt to locate it automatically via chrome-launcher.
Install Chrome or Chromium:
# Download Chrome
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

# Or install Chromium
sudo apt install chromium-browser
Install Chrome for Linux inside WSL, not Windows Chrome:
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f  # Fix dependencies

​
Permission errors

If you encounter permission issues during installation: 
# Fix npm permissions (don't use sudo with npm install -g)
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
Then reinstall: 
npm install -g browser-debugger-cli@alpha

​
Port conflicts

If you see port already in use errors: 
# Check what's using the default CDP port (9222)
lsof -i :9222

# Kill the process or use a different port
bdg example.com --port 9223

​
Next Steps

Now that bdg is installed, you’re ready to start using it:

Quickstart

Start your first debugging session in 60 seconds

Core Concepts

Learn how bdg sessions work

Command Reference

Explore all available commands

Troubleshooting

Get help with common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us