playwright-cdp-cli

🎭 CLI tool to control Playwright browsers via Chrome DevTools Protocol (CDP). Perfect for connecting to existing Chrome instances with UC mode support.

✨ Features

• 🔌 Connect to any CDP endpoint (Chrome, Edge, UC Chrome, etc.)
• 🚀 Simple command-line interface
• 🎯 Environment variable support (CDP_ENDPOINT)
• 🤖 Perfect for UC mode browsers (undetected-chrome)
• 📦 No browser installation required (uses existing instances)
• ⚡ Fast and lightweight
• ✅ CAPTCHA Detection - Auto-detect Cloudflare Turnstile, Google reCAPTCHA, and more

📦 Installation

# Global installation
npm install -g playwright-cdp-cli

# Or use with npx (no installation needed)
npx playwright-cdp-cli goto https://example.com

🚀 Quick Start

Set CDP Endpoint (Recommended)

# Set environment variable
export CDP_ENDPOINT=http://localhost:9222

# Now use commands without --cdp-endpoint flag
playwright-cdp-cli goto https://example.com
playwright-cdp-cli screenshot test.png

Or Use Flag

playwright-cdp-cli --cdp-endpoint=http://localhost:9222 goto https://example.com

📋 Available Commands

Navigation

• goto <url> - Navigate to URL
• go-back - Go to previous page
• go-forward - Go to next page
• reload - Reload current page

Interaction

• fill <selector> <text> - Fill input field
• click <selector> - Click element
• select <selector> <value> - Select dropdown option
• check <selector> - Check checkbox
• uncheck <selector> - Uncheck checkbox
• hover <selector> - Hover over element
• type <text> - Type text
• press <key> - Press keyboard key

Inspection

• snapshot - Get element references
• eval <code> - Evaluate JavaScript
• console - Monitor console messages
• screenshot [filename] - Take screenshot
• detect-captcha - NEW Detect CAPTCHA type
• get-page-info - NEW Get page information

# Fill input field
playwright-cdp-cli fill <selector> <text>

# Click element
playwright-cdp-cli click <selector>

# Type text
playwright-cdp-cli type <text>

Capture

# Take screenshot
playwright-cdp-cli screenshot [filename]

# Default filename: screenshot-{timestamp}.png
playwright-cdp-cli screenshot

Evaluation

# Evaluate JavaScript
playwright-cdp-cli eval <code>

# Examples
playwright-cdp-cli eval "document.title"
playwright-cdp-cli eval "window.location.href"
playwright-cdp-cli eval "navigator.userAgent"

DevTools

# Monitor console messages
playwright-cdp-cli console

💡 Use Cases

1. Automation Scripts - Control browsers from bash scripts
2. UC Mode Integration - Connect to undetected-chromedriver instances
3. CAPTCHA Detection - Detect and monitor CAPTCHAs during automation
4. Remote Browser Control - Control browsers on remote servers
5. Testing - Quick browser testing without writing full scripts
6. Docker Integration - Control browsers in Docker containers

🤖 CAPTCHA Detection (NEW in v1.2.0)

Automatically detect CAPTCHAs based on SeleniumBase detection patterns:

Supported CAPTCHA Types:

• ✅ Cloudflare Turnstile
• ✅ Google reCAPTCHA v2
• ✅ Cloudflare Challenge Pages

Examples:

# Detect CAPTCHA on current page
playwright-cdp-cli detect-captcha

# Output:
# 🔍 Detecting CAPTCHA...
# ⚠️  CAPTCHA detected: cloudflare_turnstile
# 📋 Possible selectors:
#    ✅ .cf-turnstile-wrapper
#    ✅ [class="cf-turnstile"]

# Wait for CAPTCHA to be solved (useful with UC mode)
playwright-cdp-cli wait-for-no-captcha 30

# Get page info including CAPTCHA status
playwright-cdp-cli get-page-info
# Output:
# 📊 Page Information:
#    Title: Example Page
#    URL: https://example.com
#    CAPTCHA: cloudflare_turnstile

Auto-Solve CAPTCHA (NEW in v1.2.1):

# Automatically solve CAPTCHA
playwright-cdp-cli goto https://protected-site.com
playwright-cdp-cli solve-captcha

# Output:
# 🤖 Attempting to solve CAPTCHA...
# ⚠️  CAPTCHA detected: cloudflare_turnstile
# 🔄 Solving Cloudflare Turnstile...
#    Found element: [class="cf-turnstile"]
#    ✅ Clicked CAPTCHA element
# ✅ Turnstile solved

Integration with UC Mode:

# Option 1: Let UC mode solve it automatically
playwright-cdp-cli goto https://protected-site.com
playwright-cdp-cli wait-for-no-captcha 30

# Option 2: Manually trigger solve
playwright-cdp-cli goto https://protected-site.com
playwright-cdp-cli solve-captcha

# Option 3: Detect first, then solve
playwright-cdp-cli detect-captcha
playwright-cdp-cli solve-captcha

# Continue automation
playwright-cdp-cli fill "#email" "[email protected]"

📋 Available Commands

Navigation

• goto <url> - Navigate to URL
• go-back - Go to previous page
• go-forward - Go to next page
• reload - Reload current page

Interaction

• fill <selector> <text> - Fill input field
• click <selector> - Click element
• select <selector> <value> - Select dropdown option
• check <selector> - Check checkbox
• uncheck <selector> - Uncheck checkbox
• hover <selector> - Hover over element
• type <text> - Type text
• press <key> - Press keyboard key

Inspection

• snapshot - Get element references
• eval <code> - Evaluate JavaScript
• console - Monitor console messages
• screenshot [filename] - Take screenshot
• detect-captcha - NEW Detect CAPTCHA type
• get-page-info - NEW Get page information

🎯 Use Cases

1. Connect to UC Chrome Server

Perfect for connecting to undetected Chrome instances:

# Start UC Chrome CDP server (e.g., tuxed/cdp-browser)
docker run -d -p 9222:9222 tuxed/cdp-browser:latest

# Set endpoint
export CDP_ENDPOINT=http://localhost:9222

# Use commands
playwright-cdp-cli goto https://bot.sannysoft.com
playwright-cdp-cli screenshot bot-test.png

2. Form Automation

export CDP_ENDPOINT=http://localhost:9222

playwright-cdp-cli goto https://example.com/form
playwright-cdp-cli fill "#email" "[email protected]"
playwright-cdp-cli fill "#password" "secret123"
playwright-cdp-cli click "button[type='submit']"
playwright-cdp-cli screenshot form-submitted.png

3. Web Scraping

playwright-cdp-cli goto https://example.com
playwright-cdp-cli eval "document.querySelector('h1').textContent"
playwright-cdp-cli eval "Array.from(document.querySelectorAll('a')).map(a => a.href)"

4. Testing & Debugging

# Navigate and inspect
playwright-cdp-cli goto https://example.com
playwright-cdp-cli console  # Monitor console messages
playwright-cdp-cli eval "document.readyState"
playwright-cdp-cli screenshot debug.png

🔧 Configuration

Environment Variables

# CDP endpoint (recommended)
export CDP_ENDPOINT=http://localhost:9222

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export CDP_ENDPOINT=http://localhost:9222' >> ~/.bashrc
source ~/.bashrc

Aliases

# Create short alias
alias pwcdp='playwright-cdp-cli'

# Use
pwcdp goto https://example.com
pwcdp screenshot test.png

🐳 Docker Integration

Works perfectly with CDP-enabled Docker containers:

# Start UC Chrome CDP server
docker run -d \
  --name uc-chrome \
  -p 9222:9222 \
  --shm-size=2gb \
  tuxed/cdp-browser:latest

# Connect and use
export CDP_ENDPOINT=http://localhost:9222
playwright-cdp-cli goto https://example.com

🤖 UC Mode Support

This tool is perfect for connecting to UC (Undetected Chrome) instances:

# UC Chrome evades bot detection
playwright-cdp-cli goto https://bot.sannysoft.com
playwright-cdp-cli eval "navigator.webdriver"  # undefined (not detected!)
playwright-cdp-cli screenshot bot-test.png

📝 Examples

Complete Form Filling Script

#!/bin/bash
export CDP_ENDPOINT=http://localhost:9222

# Navigate
playwright-cdp-cli goto https://example.com/form

# Fill fields
playwright-cdp-cli fill "#name" "John Doe"
playwright-cdp-cli fill "#email" "[email protected]"
playwright-cdp-cli fill "#message" "Hello World"

# Submit
playwright-cdp-cli click "button[type='submit']"

# Verify
sleep 2
playwright-cdp-cli screenshot submitted.png

Bot Detection Test

#!/bin/bash
export CDP_ENDPOINT=http://localhost:9222

# Test on bot detection sites
playwright-cdp-cli goto https://bot.sannysoft.com
sleep 3
playwright-cdp-cli screenshot sannysoft.png

playwright-cdp-cli goto https://intoli.com/blog/not-possible-to-block-chrome-headless/chrome-headless-test.html
sleep 3
playwright-cdp-cli screenshot intoli.png

🆚 Comparison

| Feature | playwright-cdp-cli | Playwright CLI | Puppeteer | |---------|-------------------|----------------|-----------| | Connect to existing browser | ✅ | ❌ | ✅ | | UC mode support | ✅ | ❌ | ❌ | | Simple CLI | ✅ | ⚠️ | ❌ | | No browser install needed | ✅ | ❌ | ❌ | | Environment variables | ✅ | ❌ | ❌ |

🔗 Related Projects

• tuxed/cdp-browser - UC Chrome CDP Docker image
• Playwright - Browser automation library
• SeleniumBase - UC mode implementation

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

Found a bug? Open an issue

👤 Author

tuxed

Made with ❤️ for browser automation enthusiasts