chrome-cdp-cli 1.7.5 → 1.7.7

package/README.md

@@ -1,41 +1,16 @@
 # Chrome DevTools CLI
 
+A command-line tool for browser automation via Chrome DevTools Protocol (CDP). Designed for developers who need reliable, scriptable browser control with both dedicated commands and flexible JavaScript execution.
 
-A command-line tool designed specifically for Large Language Models (LLMs) and AI-assisted development. Controls Chrome browser via Chrome DevTools Protocol (CDP) with an **eval-first design philosophy** - most automation tasks use JavaScript execution because LLMs excel at writing and validating scripts quickly.
+## 🤔 Why This Tool Exists
 
-## 🚀 Built for LLMs - Eval-First Design Philosophy
+**The honest story:** I started using `chrome-devtools-mcp` like everyone else. It worked great... until it didn't. One day it just stopped working - Cursor showed 26 tools available, everything looked normal, but every single tool call threw errors. Classic black box problem: you can't debug what you can't see inside.
 
-**This tool is specifically designed for Large Language Models (LLMs) and AI-assisted development.**
+**The MCP reality check:** Model Context Protocol sounded promising, but let's be real - it's not exactly taking the world by storm. Meanwhile, Anthropic introduced the SKILL concept, which actually makes sense for how LLMs work. And what pairs perfectly with Skills? Good old-fashioned command-line tools. They're debuggable, efficient, and you can actually see what's happening when things go wrong.
 
-### Why Most Commands Use Eval
+**The pragmatic solution:** Instead of wrestling with mysterious MCP failures, why not build a CLI that just works? One that you can debug, extend, and actually understand. Plus, when your AI assistant needs to automate a browser, it can just write the command and execute it - no black boxes, no mysterious failures, just straightforward automation.
 
-**The core design principle:** Most browser automation tasks are accomplished through the `eval` command rather than dedicated CLI commands. This is intentional and optimized for LLM workflows:
-
-1. **🧠 LLMs Excel at JavaScript**: Large Language Models are exceptionally good at writing JavaScript code. They can generate complex automation scripts, handle async operations, and adapt to different scenarios - all in JavaScript.
-
-2. **⚡ Rapid Script Validation**: LLMs can write a script, test it immediately with `eval`, see the results, and refine it in seconds. This iterative loop is where LLMs shine.
-
-3. **🔄 Maximum Flexibility**: Instead of waiting for specific commands to be implemented, LLMs can accomplish any browser task through JavaScript execution. Need to click an element? `document.querySelector('#btn').click()`. Need to wait for content? `await new Promise(...)`. Need complex data extraction? Just write the JavaScript.
-
-4. **🎯 Perfect for AI Workflows**: When you ask Claude or Cursor to automate a browser task, they can write the JavaScript directly - no need to learn complex CLI syntax or wait for feature implementations.
-
-### IDE Integration for LLM Workflows
-
-**Built-in support for AI development environments:**
-
-- **🖥️ Cursor Commands**: Install with `install-cursor-command` - brings browser automation directly into Cursor's command palette
-- **🤖 Claude Skills**: Install with `install-claude-skill` - enables Claude to use browser automation in conversations
-- **⚡ Seamless Integration**: AI assistants can generate automation scripts and execute them instantly through these integrations
-
-**Why this matters:** When LLMs are integrated into your IDE, they can write browser automation scripts as part of your development workflow. The eval-first approach means they can accomplish any task without waiting for specific command implementations.
-
-### The LLM Advantage
-
-- **🧠 Natural Language → JavaScript**: Ask an LLM "click the submit button" → it generates `document.querySelector('#submit').click()`
-- **⚡ Instant Testing**: Write, execute, see results, refine - all in seconds
-- **🔄 Iterative Refinement**: LLMs can adjust scripts based on results immediately
-- **📚 Context-Aware**: AI understands your project and can write automation scripts that fit your specific needs
-- **🎯 No Learning Curve**: LLMs already know JavaScript - no need to learn CLI-specific syntax
+**The result:** A tool that's both powerful enough for complex automation and simple enough that you (and your AI assistant) can actually use it without pulling your hair out.
 
 ## Implementation Status
 
@@ -51,39 +26,39 @@ A command-line tool designed specifically for Large Language Models (LLMs) and A
 - 🛠️ **IDE Integration**: Install Cursor commands and Claude skills with directory validation and --force option
 - 📦 **Build System**: Complete TypeScript build pipeline with testing framework
 
-### 🚧 Eval-First Design - LLM-Optimized Features
+### 🚧 Available via JavaScript Execution
 
-These features use the `eval` command by design (not as workarounds) - this is the intended approach for LLM-assisted development:
+For maximum flexibility, many advanced features are available through the `eval` command. This approach is particularly powerful for AI assistants and complex automation scenarios:
 
 - 📄 **Page Navigation**: `eval "window.location.href = 'https://example.com'"`
 - 🚀 **Performance Data**: `eval "performance.now()"` or `eval "performance.getEntriesByType('navigation')"`
 - 📱 **User Agent**: `eval "navigator.userAgent"`
 - 🌐 **Network Requests**: `eval "fetch('/api').then(r => r.json())"`
 
-**Why this design is optimal for LLMs:**
+**Why JavaScript execution is powerful:**
 
-1. **LLMs are JavaScript experts**: They can write complex automation scripts instantly
-2. **Rapid validation**: Write → Execute → See Results → Refine - perfect for LLM workflows
-3. **No feature waiting**: LLMs can accomplish any task through JavaScript without waiting for CLI command implementations
-4. **Natural workflow**: When you ask an LLM to automate something, it writes JavaScript - exactly what `eval` executes
-5. **Maximum flexibility**: Any browser API, any complexity level, any scenario - all through JavaScript
+1. **Universal capability**: Any browser API, any complexity level, any scenario
+2. **Rapid prototyping**: Write → Execute → See Results → Refine
+3. **AI-friendly**: Perfect for AI assistants that excel at JavaScript
+4. **No waiting**: Accomplish tasks immediately without waiting for feature implementations
+5. **Maximum flexibility**: Handle edge cases and custom scenarios easily
 
-**This is not a limitation - it's a feature designed specifically for AI-assisted development.**
+**This provides both dedicated commands for common tasks and unlimited flexibility through JavaScript execution.**
 
-### 🎯 IDE Integration - Built for LLM Workflows
+### 🎯 IDE Integration - Built for Modern Development
 
 **Why we support Cursor Commands & Claude Skills:**
 
-This tool is designed for LLM-assisted development. The IDE integrations (`install-cursor-command` and `install-claude-skill`) bring browser automation directly into AI-powered development environments:
+This tool integrates seamlessly with modern AI-powered development environments. The IDE integrations (`install-cursor-command` and `install-claude-skill`) bring browser automation directly into your workflow:
 
-- **🔄 Seamless LLM Workflow**: AI assistants can write and execute browser automation scripts directly in your IDE
-- **🧠 AI-Native Design**: The eval-first approach means LLMs can accomplish any browser task through JavaScript
-- **⚡ Instant Script Validation**: LLMs write JavaScript → execute via eval → see results → refine - all in real-time
-- **📚 Context-Aware Automation**: AI understands your project context and can generate relevant automation scripts
-- **🎯 Natural Language → Automation**: Ask "click the submit button" → AI generates `document.querySelector('#submit').click()` → executes instantly
+- **🔄 Seamless Workflow**: AI assistants can write and execute browser automation scripts directly in your IDE
+- **🧠 Natural Integration**: JavaScript execution means AI can accomplish any browser task
+- **⚡ Instant Execution**: Write scripts → execute via commands → see results → refine in real-time
+- **📚 Context-Aware**: AI understands your project context and generates relevant automation
+- **🎯 Natural Language → Automation**: Ask "click the submit button" → AI generates and executes the solution
 - **🤖 Perfect for AI Assistants**: Claude and Cursor can use browser automation as part of their toolset
 
-**The integration exists because this tool is built for LLMs - the eval-first design and IDE integrations work together to enable AI-powered browser automation.**
+**The integration exists because modern development is AI-assisted - these tools work together to enable efficient browser automation.**
 
 ### ⏳ Not Yet Implemented
 
@@ -144,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
@@ -437,7 +422,7 @@ chrome-cdp-cli install_cursor_command --force
 chrome-cdp-cli install_claude_skill --force
 ```
 
-### 🚧 Available via Eval Workarounds
+### 🚧 Available via JavaScript Execution
 
 #### Page Management
 ```bash
@@ -464,7 +449,7 @@ chrome-cdp-cli click "#button"
 chrome-cdp-cli hover ".menu-item"
 chrome-cdp-cli fill "#email" "user@example.com"
 
-# Via eval (still available for complex scenarios)
+# Via JavaScript execution (flexible for complex scenarios)
 chrome-cdp-cli eval "document.querySelector('#button').click()"
 chrome-cdp-cli eval "document.querySelector('.menu-item').dispatchEvent(new MouseEvent('mouseover'))"
 chrome-cdp-cli eval "document.querySelector('#email').value = 'user@example.com'"
@@ -492,7 +477,7 @@ chrome-cdp-cli fill_form --fields '[
 chrome-cdp-cli fill "#name" "John Doe"
 chrome-cdp-cli fill "#email" "john@example.com"
 
-# Via eval (for complex form operations)
+# Via JavaScript execution (for complex form operations)
 chrome-cdp-cli eval "
 document.querySelector('#name').value = 'John Doe';
 document.querySelector('#email').value = 'john@example.com';
@@ -505,7 +490,7 @@ chrome-cdp-cli eval "document.querySelector('#myform').submit()"
 # Select dropdown option (native)
 chrome-cdp-cli fill "#dropdown" "option1"
 
-# Select dropdown option (via eval)
+# Select dropdown option (via JavaScript execution)
 chrome-cdp-cli eval "document.querySelector('#dropdown').value = 'option1'"
 
 # Check checkbox
@@ -690,25 +675,25 @@ new Promise(resolve => {
    - Quiet and verbose modes
    - Custom output templates
 
-### Why Eval-First Design? (Built for LLMs)
+### Why JavaScript Execution? (Built for Modern Development)
 
-**This is not a workaround - it's the core design philosophy optimized for LLM workflows:**
+**This is not a workaround - it's a core design philosophy optimized for modern development workflows:**
 
-1. **🧠 LLMs are JavaScript Experts**: Large Language Models excel at writing JavaScript. They can generate complex automation scripts, handle async operations, and adapt to different scenarios - all naturally in JavaScript.
+1. **🧠 Universal Language**: JavaScript is the language of the web. Developers and AI assistants alike excel at writing JavaScript for browser automation.
 
-2. **⚡ Rapid Script Validation**: The perfect workflow for LLMs: Write JavaScript → Execute via `eval` → See Results → Refine. This iterative loop is where LLMs shine.
+2. **⚡ Rapid Prototyping**: The perfect workflow: Write JavaScript → Execute → See Results → Refine. This iterative loop is ideal for both human developers and AI assistants.
 
 3. **🔄 Maximum Flexibility**: Any browser task, any complexity, any scenario - all through JavaScript. No waiting for specific command implementations.
 
-4. **🤖 AI-Native Workflow**: When you ask Claude or Cursor to automate something, they write JavaScript - exactly what `eval` executes. Perfect alignment.
+4. **🤖 AI-Native Workflow**: When you ask Claude or Cursor to automate something, they naturally write JavaScript - exactly what the `eval` command executes.
 
 5. **📚 Natural Language → Automation**: "Click the submit button" → AI generates `document.querySelector('#submit').click()` → Executes instantly.
 
 6. **🎯 Context-Aware**: AI understands your project and can write automation scripts that fit your specific needs.
 
-7. **⚡ Instant Iteration**: LLMs can adjust scripts based on results immediately - no need to wait for feature releases.
+7. **⚡ Instant Iteration**: Both developers and AI can adjust scripts based on results immediately - no need to wait for feature releases.
 
-**This tool is built for LLM-assisted development. The eval-first approach, combined with IDE integrations (Cursor commands & Claude skills), creates a seamless workflow where AI assistants can automate browser tasks as part of your development process.**
+**This tool bridges the gap between dedicated commands for common tasks and unlimited flexibility through JavaScript execution, making it perfect for both traditional development and AI-assisted workflows.**
 
 ## Form Filling & Element Interaction
 
@@ -1044,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
 
@@ -1077,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/dist/cli/CLIApplication.js

@@ -35,28 +35,45 @@ class CLIApplication {
         this.cli.registerHandler(new handlers_1.WaitForHandler());
         this.cli.registerHandler(new handlers_1.HandleDialogHandler());
     }
+    configureDebugMode(debug) {
+        const registry = this.cli.getRegistry();
+        const handlerNames = registry.getCommandNames();
+        for (const handlerName of handlerNames) {
+            const handler = registry.get(handlerName);
+            if (handler && typeof handler.setDebug === 'function') {
+                handler.setDebug(debug);
+            }
+        }
+    }
     async run(argv) {
         try {
-            console.log('[DEBUG] CLIApplication.run called with argv:', argv);
             const command = this.cli.parseArgs(argv);
-            console.log('[DEBUG] Parsed command:', command);
+            if (command.config.debug) {
+                this.logger.setLevel(3);
+            }
+            else {
+                this.logger.setLevel(2);
+            }
+            this.configureDebugMode(command.config.debug);
+            this.logger.debug('CLIApplication.run called with argv:', argv);
+            this.logger.debug('Parsed command:', command);
             if (command.config.verbose) {
                 this.proxyManager.setLogging(true);
             }
-            console.log('[DEBUG] Ensuring proxy is ready...');
+            this.logger.debug('Ensuring proxy is ready...');
             await this.ensureProxyReady();
             if (this.needsConnection(command.name)) {
-                console.log('[DEBUG] Command needs connection, ensuring connection...');
+                this.logger.debug('Command needs connection, ensuring connection...');
                 await this.ensureConnection(command);
             }
-            console.log('[DEBUG] Executing command via CLI interface...');
+            this.logger.debug('Executing command via CLI interface...');
             const result = await this.cli.execute(command);
-            console.log('[DEBUG] Command execution result:', result);
+            this.logger.debug('Command execution result:', result);
             this.outputResult(result, command);
             return result.exitCode || (result.success ? CommandRouter_1.ExitCode.SUCCESS : CommandRouter_1.ExitCode.GENERAL_ERROR);
         }
         catch (error) {
-            console.log('[DEBUG] Error in CLIApplication.run:', error);
+            this.logger.debug('Error in CLIApplication.run:', error);
             const errorMessage = error instanceof Error ? error.message : String(error);
             console.error(`Error: ${errorMessage}`);
             return CommandRouter_1.ExitCode.GENERAL_ERROR;

package/dist/cli/CLIInterface.js

@@ -61,6 +61,7 @@ class CLIInterface {
             .option('-v, --verbose', 'Enable verbose logging', CLIInterface_1.DEFAULT_CLI_CONFIG.verbose)
             .option('-q, --quiet', 'Enable quiet mode', CLIInterface_1.DEFAULT_CLI_CONFIG.quiet)
             .option('-t, --timeout <timeout>', 'Command timeout in milliseconds', (value) => parseInt(value, 10), CLIInterface_1.DEFAULT_CLI_CONFIG.timeout)
+            .option('-d, --debug', 'Enable debug logging', CLIInterface_1.DEFAULT_CLI_CONFIG.debug)
             .option('-c, --config <config>', 'Configuration file path');
     }
     parseArgs(argv) {
@@ -77,7 +78,12 @@ class CLIInterface {
                 const arg = args[i];
                 if (arg.startsWith('--')) {
                     const optionName = arg.substring(2);
-                    if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+                    const booleanFlags = ['verbose', 'quiet', 'debug'];
+                    if (booleanFlags.includes(optionName)) {
+                        options[optionName] = true;
+                        i++;
+                    }
+                    else if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
                         options[optionName] = args[i + 1];
                         i += 2;
                     }
@@ -88,7 +94,12 @@ class CLIInterface {
                 }
                 else if (arg.startsWith('-') && arg.length > 1) {
                     const shortOption = arg.substring(1);
-                    if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+                    const booleanShortFlags = ['v', 'q', 'd'];
+                    if (booleanShortFlags.includes(shortOption)) {
+                        options[shortOption] = true;
+                        i++;
+                    }
+                    else if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
                         options[shortOption] = args[i + 1];
                         i += 2;
                     }
@@ -114,6 +125,8 @@ class CLIInterface {
                 options.quiet = true;
             if (options.t)
                 options.timeout = parseInt(options.t, 10);
+            if (options.d)
+                options.debug = true;
             if (options.c)
                 options.config = options.c;
             if (options.port && typeof options.port === 'string') {
@@ -163,7 +176,8 @@ class CLIInterface {
             outputFormat: cliOptions.format || fileConfig.outputFormat || CLIInterface_1.DEFAULT_CLI_CONFIG.outputFormat,
             verbose: cliOptions.verbose || fileConfig.verbose || CLIInterface_1.DEFAULT_CLI_CONFIG.verbose,
             quiet: cliOptions.quiet || fileConfig.quiet || CLIInterface_1.DEFAULT_CLI_CONFIG.quiet,
-            timeout: cliOptions.timeout || fileConfig.timeout || CLIInterface_1.DEFAULT_CLI_CONFIG.timeout
+            timeout: cliOptions.timeout || fileConfig.timeout || CLIInterface_1.DEFAULT_CLI_CONFIG.timeout,
+            debug: cliOptions.debug || fileConfig.debug || CLIInterface_1.DEFAULT_CLI_CONFIG.debug
         };
     }
     loadConfigFile(configPath) {
@@ -199,6 +213,9 @@ class CLIInterface {
         if (config.timeout !== undefined && (typeof config.timeout !== 'number' || config.timeout < 1)) {
             throw new Error('Configuration "timeout" must be a positive number');
         }
+        if (config.debug !== undefined && typeof config.debug !== 'boolean') {
+            throw new Error('Configuration "debug" must be a boolean');
+        }
     }
     extractCommandArgs(command, args, options) {
         const commandArgs = {};

package/dist/cli/CommandRouter.js

@@ -169,18 +169,24 @@ class CommandRouter {
     }
     async executeWithTimeout(handler, command) {
         const timeout = command.config.timeout;
-        console.log(`[DEBUG] CommandRouter.executeWithTimeout called for command: ${command.name}, timeout: ${timeout}ms`);
+        if (command.config.debug) {
+            this.logger.setLevel(3);
+        }
+        else {
+            this.logger.setLevel(2);
+        }
+        this.logger.debug(`CommandRouter.executeWithTimeout called for command: ${command.name}, timeout: ${timeout}ms`);
         const timeoutPromise = new Promise((_, reject) => {
             setTimeout(() => {
-                console.log(`[DEBUG] Command timeout reached for: ${command.name} after ${timeout}ms`);
+                this.logger.debug(`Command timeout reached for: ${command.name} after ${timeout}ms`);
                 reject(new Error(`Command timeout after ${timeout}ms`));
             }, timeout);
         });
-        console.log(`[DEBUG] Starting handler execution for: ${command.name}`);
+        this.logger.debug(`Starting handler execution for: ${command.name}`);
         const executionPromise = handler.execute(this.client, command.args);
         try {
             const result = await Promise.race([executionPromise, timeoutPromise]);
-            console.log(`[DEBUG] Command completed successfully for: ${command.name}`);
+            this.logger.debug(`Command completed successfully for: ${command.name}`);
             if (!result || typeof result !== 'object') {
                 return {
                     success: false,
@@ -194,7 +200,7 @@ class CommandRouter {
             return result;
         }
         catch (error) {
-            console.log(`[DEBUG] Command execution error for: ${command.name}:`, error);
+            this.logger.debug(`Command execution error for: ${command.name}:`, error);
             if (error instanceof Error && error.message.includes('timeout')) {
                 return {
                     success: false,
@@ -218,6 +224,7 @@ Global Options:
   -v, --verbose            Enable verbose logging
   -q, --quiet              Enable quiet mode
   -t, --timeout <ms>       Command timeout in milliseconds (default: 30000)
+  -d, --debug              Enable debug logging
   -c, --config <path>      Configuration file path
   -V, --version            Show version number
 

package/dist/handlers/EvaluateScriptHandler.js

@@ -5,16 +5,32 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvaluateScriptHandler = void 0;
 const ProxyClient_1 = require("../client/ProxyClient");
+const logger_1 = require("../utils/logger");
 const fs_1 = require("fs");
 const node_fetch_1 = __importDefault(require("node-fetch"));
 class EvaluateScriptHandler {
-    constructor(useProxy = false) {
+    constructor(useProxy = false, debug = false) {
         this.name = 'eval';
         this.proxyClient = new ProxyClient_1.ProxyClient();
         this.useProxy = useProxy;
+        this.logger = new logger_1.Logger();
+        if (debug) {
+            this.logger.setLevel(3);
+        }
+        else {
+            this.logger.setLevel(2);
+        }
+    }
+    setDebug(debug) {
+        if (debug) {
+            this.logger.setLevel(3);
+        }
+        else {
+            this.logger.setLevel(2);
+        }
     }
     async execute(client, args) {
-        console.log('[DEBUG] EvaluateScriptHandler.execute called with args:', args);
+        this.logger.debug('EvaluateScriptHandler.execute called with args:', args);
         const scriptArgs = args;
         if (!scriptArgs.expression && !scriptArgs.file) {
             return {
@@ -28,17 +44,17 @@ class EvaluateScriptHandler {
                 error: 'Cannot specify both "expression" and "file" arguments'
             };
         }
-        console.log('[DEBUG] Arguments validated, useProxy:', this.useProxy);
+        this.logger.debug('Arguments validated, useProxy:', this.useProxy);
         try {
             if (this.useProxy) {
-                console.log('[DEBUG] Checking proxy availability...');
+                this.logger.debug('Checking proxy availability...');
                 const proxyAvailable = await this.proxyClient.isProxyAvailable();
-                console.log('[DEBUG] Proxy available:', proxyAvailable);
+                this.logger.debug('Proxy available:', proxyAvailable);
                 if (proxyAvailable) {
                     console.log('[INFO] Using proxy connection for script evaluation');
-                    console.log('[DEBUG] About to call executeWithProxy...');
+                    this.logger.debug('About to call executeWithProxy...');
                     const result = await this.executeWithProxy(scriptArgs);
-                    console.log('[DEBUG] executeWithProxy returned:', result);
+                    this.logger.debug('executeWithProxy returned:', result);
                     return result;
                 }
                 else {
@@ -49,12 +65,12 @@ class EvaluateScriptHandler {
         catch (error) {
             console.warn('[WARN] Proxy execution failed, falling back to direct CDP:', error instanceof Error ? error.message : error);
         }
-        console.log('[DEBUG] Falling back to direct CDP');
+        this.logger.debug('Falling back to direct CDP');
         return await this.executeWithDirectCDP(client, scriptArgs);
     }
     async executeWithProxy(scriptArgs) {
         try {
-            console.log('[DEBUG] Starting executeWithProxy');
+            this.logger.debug('Starting executeWithProxy');
             let expression;
             if (scriptArgs.file) {
                 expression = await this.readScriptFile(scriptArgs.file);
@@ -62,10 +78,10 @@ class EvaluateScriptHandler {
             else {
                 expression = scriptArgs.expression;
             }
-            console.log('[DEBUG] Expression to execute:', expression.substring(0, 100));
-            console.log('[DEBUG] Creating new proxy connection...');
+            this.logger.debug('Expression to execute:', expression.substring(0, 100));
+            this.logger.debug('Creating new proxy connection...');
             const connectionId = await this.proxyClient.connect('localhost', 9222);
-            console.log(`[DEBUG] Created new proxy connection: ${connectionId}`);
+            this.logger.debug(`Created new proxy connection: ${connectionId}`);
             try {
                 const result = await this.executeScriptThroughHTTP(connectionId, expression, scriptArgs);
                 return {
@@ -78,7 +94,7 @@ class EvaluateScriptHandler {
             }
         }
         catch (error) {
-            console.log('[DEBUG] Error in executeWithProxy:', error);
+            this.logger.debug('Error in executeWithProxy:', error);
             return {
                 success: false,
                 error: error instanceof Error ? error.message : String(error)

package/dist/interfaces/CLIInterface.js

@@ -7,5 +7,6 @@ exports.DEFAULT_CLI_CONFIG = {
     outputFormat: 'text',
     verbose: false,
     quiet: false,
-    timeout: 30000
+    timeout: 30000,
+    debug: false
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-cdp-cli",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "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",