chrome-cdp-cli 1.7.6 → 1.7.8

package/README.md

@@ -119,19 +119,29 @@ npm link
 Before using the CLI, start Chrome with remote debugging enabled:
 
 ```bash
-# Default port (9222)
-chrome --remote-debugging-port=9222
+# Default port (9222) - IMPORTANT: Include --user-data-dir to avoid conflicts
+chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile
 
 # Custom port
-chrome --remote-debugging-port=9223
+chrome --remote-debugging-port=9223 --user-data-dir=/tmp/chrome-debug-profile
 
 # Headless mode
-chrome --headless --remote-debugging-port=9222
+chrome --headless --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile
 
 # With additional flags for automation
-chrome --remote-debugging-port=9222 --no-first-run --no-default-browser-check
+chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile --no-first-run --no-default-browser-check
+
+# macOS example with full path and logging
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/Users/$USER/chrome-profile-debug > /tmp/chrome.log 2>&1 &
 ```
 
+**Important Notes:**
+- **Always use `--user-data-dir`**: This creates a separate Chrome profile for debugging and prevents conflicts with your regular Chrome instance
+- **Choose a dedicated directory**: Use a path like `/tmp/chrome-debug-profile` or `/Users/$USER/chrome-profile-debug`
+- **Avoid profile conflicts**: Without `--user-data-dir`, Chrome may fail to open the debugging port if another instance is running
+
+For more details, see the [Chrome Remote Debugging documentation](https://developer.chrome.com/blog/remote-debugging-port).
+
 ## Quick Start
 
 ```bash
@@ -1019,18 +1029,26 @@ console.log(result);
 ### Common Issues
 
 1. **Connection Refused**
-   - Ensure Chrome is running with `--remote-debugging-port=9222`
+   - Ensure Chrome is running with `--remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug`
+   - **Always include `--user-data-dir`** to avoid profile conflicts
    - Check if the port is correct and not blocked by firewall
+   - Verify no other Chrome instances are using the same debugging port
+
+2. **Chrome Won't Start Debugging Port**
+   - **Most common cause**: Missing `--user-data-dir` parameter
+   - **Solution**: Use a dedicated profile directory: `--user-data-dir=/tmp/chrome-debug-profile`
+   - **Why needed**: Prevents conflicts with existing Chrome instances
+   - See [Chrome Remote Debugging documentation](https://developer.chrome.com/blog/remote-debugging-port) for details
 
-2. **Command Timeout**
+3. **Command Timeout**
    - Increase timeout with `--timeout` option
    - Check if the page is responsive
 
-3. **Element Not Found**
+4. **Element Not Found**
    - Verify CSS selectors are correct
    - Use `wait_for` command to wait for dynamic elements
 
-4. **Permission Denied**
+5. **Permission Denied**
    - Ensure Chrome has necessary permissions
    - Check file system permissions for screenshot output
 
@@ -1052,31 +1070,6 @@ npm run package
 npm run prepublishOnly
 ```
 
-## Publishing to npm
-
-To make this tool available via `npx`, you need to publish it to npm:
-
-```bash
-# 1. Login to npm (one time setup)
-npm login
-
-# 2. Publish the package
-npm publish
-
-# 3. Users can then use it with npx
-npx chrome-cdp-cli eval "document.title"
-```
-
-**Note**: The package name `chrome-cdp-cli` uses a clean, descriptive approach. This approach:
-
-- ✅ **Professional naming** that clearly indicates Chrome DevTools Protocol CLI
-- ✅ **Works with npx**: `npx chrome-cdp-cli eval "document.title"`
-- ✅ **Simple installation**: `npm install -g chrome-cdp-cli`
-- ✅ **Short and memorable** compared to longer alternatives
-
-Alternative naming examples:
-1. **Scoped name**: `@nickxiao42/chrome-devtools-cli`
-2. **Longer descriptive**: `chrome-automation-cli`
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-cdp-cli",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "description": "Browser automation CLI via Chrome DevTools Protocol. Designed for developers and AI assistants - combines dedicated commands for common tasks with flexible JavaScript execution for complex scenarios. Features: element interaction, screenshots, DOM snapshots, console/network monitoring. Built-in IDE integration for Cursor and Claude.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,7 +35,7 @@
     "prepublishOnly": "npm run test:ci && npm run build:prod",
     "prepack": "npm run build:prod",
     "verify": "npm run lint && npm run test:ci && npm run build:prod",
-    "postinstall": "node -e \"console.log('\\n🎉 chrome-cdp-cli installed successfully!\\n\\n📋 Quick Start:\\n  1. Start Chrome with debugging: chrome --remote-debugging-port=9222\\n  2. Try: chrome-cdp-cli eval \\\"document.title\\\"\\n  3. Get help: chrome-cdp-cli --help\\n\\n🔗 More info: https://github.com/nicoster/chrome-devtools-cli\\n')\""
+    "postinstall": "node -e \"console.log('\\n🎉 chrome-cdp-cli installed successfully!\\n\\n📋 Quick Start:\\n  1. Start Chrome with debugging: chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug\\n  2. Try: chrome-cdp-cli eval \\\"document.title\\\"\\n  3. Get help: chrome-cdp-cli --help\\n\\n🔗 More info: https://github.com/nicoster/chrome-devtools-cli\\n')\""
   },
   "keywords": [
     "chrome",