diff --git a/README.md b/README.md
index d250f59..a41ce4f 100644
--- a/README.md
+++ b/README.md
@@ -1,59 +1,22 @@
-# Chrome DevTools CLI
+# chrome-devtools-cli
 
-Rust CLI that connects to an existing Chrome browser via the DevTools Protocol. Auto-connects by default — no manual WebSocket URL needed.
+A high-performance, developer-friendly CLI for interacting with Chrome via the DevTools Protocol (CDP).
 
-[![crates.io](https://img.shields.io/crates/v/chrome-devtools-cli.svg)](https://crates.io/crates/chrome-devtools-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aeroxy/chrome-devtools-cli)
+## Key Features
 
-## Installation
-
-### Homebrew (macOS, recommended)
-
-```bash
-brew install aeroxy/tap/chrome-devtools
-```
-
-### Cargo
-
-```bash
-cargo install chrome-devtools-cli
-```
+- **Page Emulation**: Manage viewport size, mobile device emulation, device scale factor, and geolocation overrides in one place.
+- **Smart Navigation**: URL navigation, back/forward, and reload with automatic page-load waiting and custom HTTP headers.
+- **Visual Tools**: High-quality screenshots (including full-page) and accessibility tree snapshots.
+- **Interaction**: Click, fill, type, and hover using CSS selectors or coordinates.
+- **JS Evaluation**: Run JavaScript on the page with support for handling dialogs.
+- **3rd Party Integration**: Access tools exposed by pages via custom protocol extensions.
 
-The installed binary is named `chrome-devtools`.
-
-### Build from source
+## Installation
 
 ```bash
-cargo build --release
-# Binary: ./target/release/chrome-devtools
+cargo install --path .
 ```
 
-## Why this exists
-
-Inspired by [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) — the official MCP server for Chrome DevTools. It works well, but MCP-based browser tools consume a lot of token context: every interaction sends and receives large protocol payloads through the MCP layer.
-
-99% of the time the browser being controlled is the user's own Chrome with their own credentials, so there is no need for a full headless browser stack like Puppeteer or Playwright, and no need for the MCP overhead.
-
-This is a lightweight Rust binary that talks directly to Chrome's DevTools Protocol. One command in, one result out. No separate browser process, no credential handoff, no heavyweight runtime. The agent skill for this tool is a single `SKILL.md` file — the entire context overhead is this documentation.
-
-## Architecture
-
-```
-chrome-devtools navigate https://example.com
-        │
-        ├─ Try daemon (Unix socket /tmp/chrome-devtools-daemon.sock)
-        │   └─ If running → send command → get result
-        │
-        ├─ If no daemon → spawn one (background process)
-        │   └─ Daemon connects to Chrome WebSocket (one-time approval)
-        │   └─ Listens on Unix socket, 5-min idle timeout
-        │
-        └─ Fallback → direct WebSocket connection (no daemon)
-```
-
-The daemon keeps a persistent WebSocket connection to Chrome, so the browser only prompts for DevTools access once. Subsequent commands reuse the connection.
-
 ## Prerequisites
 
 Chrome must have remote debugging enabled:
@@ -62,168 +25,57 @@ Chrome must have remote debugging enabled:
 2. Go to `chrome://inspect/#remote-debugging`
 3. Enable the remote debugging server
 
-## Auto-connect
-
-By default, the CLI reads `DevToolsActivePort` from Chrome's user data directory:
-
-| OS | Default path |
-|----|-------------|
-| macOS | `~/Library/Application Support/Google/Chrome/` |
-| Linux | `~/.config/google-chrome/` |
-| Windows | `%LOCALAPPDATA%\Google\Chrome\User Data\` |
-
-Override with `--user-data-dir`, `--channel` (beta/canary/dev), or `--ws-endpoint`. All three also read from environment variables:
-
-| Environment Variable | Corresponding Flag |
-|----------------------|--------------------|
-| `CHROME_WS_ENDPOINT` | `--ws-endpoint` |
-| `CHROME_USER_DATA_DIR` | `--user-data-dir` |
-| `CHROME_CHANNEL` | `--channel` |
-
-## Page targeting
-
-Every page-level command outputs a friendly target name like `[target:red-snake]`. This is a deterministic word-pair derived from Chrome's internal target ID — same page always gets the same name.
+## Quick Start
 
+### General Usage
 ```bash
-# Navigate — note the target name
-chrome-devtools navigate https://example.com
-# Navigated to https://example.com
-# [target:red-snake]
-
-# Pin subsequent commands to the same page
-chrome-devtools --target red-snake screenshot --output /tmp/page.png
-chrome-devtools --target red-snake evaluate "document.title"
+chrome-devtools list-pages
+chrome-devtools --page 0 navigate https://google.com
+chrome-devtools --target main screenshot --output screenshot.png
 ```
 
-Without `--target`, commands default to page index 0, which may vary as Chrome reorders tabs. Always capture and reuse the target name.
-
-`list-pages` shows all pages with their friendly names:
+### Emulation (Page-level Overrides)
+Overrides like viewport size and geolocation are persistent per page.
 
-```
-[0] (green-dog) My App — https://localhost:3000
-[1] (red-snake) Example Domain — https://example.com
-[2] (bold-stag) GitHub — https://github.com
-```
-
-You can also use `--page <index>` for quick one-offs, or pass the raw hex target ID.
-
-## Commands
+```bash
+# Set viewport and geolocation
+chrome-devtools emulate --viewport 1280x720 --geolocation 37.77,-122.41
 
-### Navigation
+# Emulate mobile device
+chrome-devtools emulate --viewport 375x812 --mobile --device-scale-factor 3
 
-| Command | Description |
-|---------|-------------|
-| `navigate <url>` | Go to URL (waits for load) |
-| `navigate --back` | Go back in history |
-| `navigate --forward` | Go forward |
-| `navigate --reload` | Reload page |
-| `new-page <url>` | Open new tab |
-| `close-page <index>` | Close tab by index |
-| `select-page <index>` | Bring tab to front |
-| `list-pages` | List all open tabs |
+# Navigate with emulation
+chrome-devtools navigate https://example.com --viewport 1920x1080 --mobile
 
-### Inspection
+# Open new tab with emulation
+chrome-devtools new-page https://example.com --viewport 375x812 --geolocation 40.71,-74.00
 
-| Command | Description |
-|---------|-------------|
-| `screenshot --output <path>` | Save screenshot to file |
-| `screenshot --full-page` | Capture full scrollable page |
-| `evaluate <expr> [--dialog-action <action>]` | Run JavaScript (optionally handle dialogs: accept, dismiss, or prompt text) |
-| `snapshot` | Accessibility tree dump |
+# Clear overrides
+chrome-devtools emulate --clear-all
+chrome-devtools emulate --clear-viewport
+chrome-devtools emulate --clear-geolocation
+```
 
 ### Interaction
-
-| Command | Description |
-|---------|-------------|
-| `click <selector>` | Click element by CSS selector |
-| `click-at <x> <y>` | Click at specific coordinates |
-| `fill <selector> <value>` | Fill input field, dropdown (`<select>`), or toggle checkbox/radio (`"true"`/`"false"`) |
-| `type-text <text> [--submit-key <key>]` | Type into focused element (optionally press key after) |
-| `press-key <key>` | Press key (e.g. `Enter`, `Control+A`) |
-| `hover <selector>` | Hover over element |
-
-### Third-party developer tools
-
-| Command | Description |
-|---------|-------------|
-| `list-3p-tools` | List custom developer tools exposed via `window.__dtmcp` |
-| `execute-3p-tool <name> <params>` | Execute a custom tool by name with a JSON params string |
-
-These commands interact with tools injected into the page via `window.__dtmcp.toolGroup` / `window.__dtmcp.executeTool`.
-
-### Other
-
-| Command | Description |
-|---------|-------------|
-| `resize <w> <h>` | Set viewport size |
-| `wait-for <text> [--timeout ms]` | Wait for text to appear (default 30s) |
-
-## Global options
-
-| Flag | Description |
-|------|-------------|
-| `--target <name>` | Target page by friendly name or raw ID |
-| `--page <index>` | Target page by index |
-| `--json` | JSON output |
-| `--ws-endpoint <url>` | Explicit WebSocket URL |
-| `--user-data-dir <path>` | Custom Chrome profile directory |
-| `--channel <ch>` | Chrome channel (stable/beta/canary/dev) |
-
-## Daemon details
-
-- **Socket**: `/tmp/chrome-devtools-daemon.sock`
-- **PID file**: `/tmp/chrome-devtools-daemon.pid`
-- **Idle timeout**: 5 minutes (auto-exits, cleans up socket)
-- **Protocol**: Length-prefixed JSON over Unix socket
-- **Spawned by**: First CLI invocation (transparent to user)
-- **Kill manually**: `pkill -f __daemon__` or delete the socket
-
-## Source layout
-
-```
-src/
-├── main.rs         # CLI (clap) + daemon-first dispatch
-├── cdp.rs          # Raw CDP over WebSocket (JSON-RPC)
-├── browser.rs      # Auto-connect (DevToolsActivePort)
-├── daemon.rs       # Background daemon (persistent connection)
-├── client.rs       # Talks to daemon via Unix socket
-├── protocol.rs     # IPC message types
-├── friendly.rs     # Target ID → word-pair names
-└── commands/
-    ├── navigate.rs
-    ├── pages.rs    # list/new/close/select/resize/wait-for
-    ├── screenshot.rs
-    ├── evaluate.rs
-    ├── input.rs    # click/fill/type/press/hover
-    ├── snapshot.rs
-    └── third_party.rs  # list-3p-tools/execute-3p-tool
+```bash
+chrome-devtools click "button.submit"
+chrome-devtools fill "input[name='q']" "searching for something"
+chrome-devtools type-text "submitting now" --submit-key Enter
 ```
 
-## Typical workflow
-
+### Custom HTTP Headers
 ```bash
-# 1. Navigate — capture the [target:name]
-chrome-devtools navigate https://example.com
-# [target:red-snake]
-
-# 2. Understand the page
-chrome-devtools --target red-snake snapshot
-chrome-devtools --target red-snake screenshot --output /tmp/page.png
-
-# 3. Interact
-chrome-devtools --target red-snake fill "#email" "user@example.com"
-chrome-devtools --target red-snake click "#submit"
+# Add authorization header
+chrome-devtools navigate https://api.example.com --extra-headers '{"Authorization":"Bearer token"}'
 
-# 4. Extract data
-chrome-devtools --target red-snake evaluate "document.title"
+# Debug headers
+chrome-devtools new-page https://example.com --extra-headers '{"X-Debug":"1"}'
 ```
 
-Always pass `--target` from step 2 onward to stay on the same page.
-
-## Agent skill
-
-`skill/chrome-devtools/SKILL.md` is a Claude Code skill that teaches the agent how to use this binary. Drop it into any Claude Code plugin's `skills/` directory and set `chrome-devtools` to the binary path. The skill covers the full workflow, all commands, and the `--target` pinning pattern — everything needed to reliably automate Chrome without large context overhead.
-
-## License
+## Global Options
 
-MIT
+- `--ws-endpoint`: Use an explicit WebSocket URL.
+- `--user-data-dir`: Auto-connect to a running Chrome instance.
+- `--page <index>`: Select page by 0-based index.
+- `--target <id>`: Select page by friendly name or ID.
+- `--json`: Format output as JSON.
diff --git a/skill/chrome-devtools/SKILL.md b/skill/chrome-devtools/SKILL.md
index f36c0a2..73e0ac8 100644
--- a/skill/chrome-devtools/SKILL.md
+++ b/skill/chrome-devtools/SKILL.md
@@ -4,10 +4,6 @@ description: Use when the user asks to "take a screenshot of a website", "naviga
 user-invocable: true
 ---
 
-# Chrome DevTools CLI
-
-A lightweight Rust binary for controlling an existing Chrome browser via the DevTools Protocol. Use this instead of MCP-based browser tools or Puppeteer-style solutions — it connects to the user's own Chrome with their own credentials, requires no headless browser or separate process, and consumes a fraction of the token context.
-
 ## Prerequisites
 
 Chrome must have remote debugging enabled:
@@ -15,102 +11,104 @@ Chrome must have remote debugging enabled:
 2. Go to `chrome://inspect/#remote-debugging`
 3. Enable the remote debugging server
 
-The binary auto-connects by reading Chrome's `DevToolsActivePort` file — no WebSocket URL needed.
+The CLI auto-connects by reading Chrome's `DevToolsActivePort` file — no WebSocket URL needed.
+
+## Core Capabilities
+
+- **Navigation**: `navigate`, `back`, `forward`, `reload`.
+- **Emulation**: `emulate` (viewport, mobile, device-scale-factor, geolocation).
+- **Extraction**: `screenshot`, `snapshot` (accessibility tree), `list-pages`.
+- **Interaction**: `click`, `click-at`, `fill`, `type-text`, `press-key`, `hover`.
+- **Execution**: `evaluate` (JS), `execute-3p-tool`.
+- **Synchronization**: `wait-for` (text on page).
 
-## Core workflow
+## Usage Guide
 
-Every page-level command prints a `[target:word-pair]` line. Capture it and pass `--target` to all subsequent commands to stay on the same tab.
+### Page Selection
+Most commands require a page target. Use `--page <index>` (0-based) or `--target <id>`.
 
 ```bash
-# Step 1: navigate, capture target name
-chrome-devtools navigate https://example.com
-# Output includes: [target:red-snake]
-
-# Step 2 onward: pin to that page
-chrome-devtools --target red-snake snapshot
-chrome-devtools --target red-snake screenshot --output /tmp/page.png
-chrome-devtools --target red-snake click "#submit"
-chrome-devtools --target red-snake evaluate "document.title"
+chrome-devtools list-pages
+chrome-devtools --target main navigate https://example.com
 ```
 
-Without `--target`, commands default to tab index 0, which may not be the right page if Chrome reorders tabs.
+### Emulation (Viewport & Geolocation)
+Overrides are persistent per page. You can set them standalone or during navigation.
 
-## Commands
+```bash
+# Set viewport and geolocation standalone
+chrome-devtools --target main emulate --viewport 1920x1080 --geolocation 40.71,-74.00
 
-### Navigation
+# Emulate mobile device
+chrome-devtools --target main emulate --viewport 375x812 --mobile --device-scale-factor 3
+
+# Navigate with atomic emulation (sets environment before loading URL)
+chrome-devtools navigate https://geotargetly.com --geolocation 51.50,-0.12
+
+# Navigate as mobile device
+chrome-devtools navigate https://example.com --viewport 375x812 --mobile
+
+# Open new tab with atomic emulation
+chrome-devtools new-page https://example.com --viewport 375x812
+
+# Clear emulation overrides
+chrome-devtools --target main emulate --clear-all
+chrome-devtools --target main emulate --clear-viewport
+chrome-devtools --target main emulate --clear-geolocation
+```
+
+### Interaction Patterns
 ```bash
-chrome-devtools navigate <url>          # Go to URL, wait for load
-chrome-devtools navigate <url> -o /tmp/res.txt # Save success/result to file
-chrome-devtools navigate --back
-chrome-devtools navigate --forward
-chrome-devtools navigate --reload
-chrome-devtools new-page <url>          # Open new tab
-chrome-devtools close-page <index>
-chrome-devtools select-page <index>
-chrome-devtools list-pages              # List all tabs with friendly names
+# Search and submit
+chrome-devtools fill "input.search" "Rust programming"
+chrome-devtools press-key Enter
+chrome-devtools wait-for "The Rust Programming Language"
+
+# Take a full-page screenshot
+chrome-devtools screenshot --full-page --output search_results.png
 ```
 
-### Inspection
+### Advanced Evaluation
 ```bash
-chrome-devtools --target <name> screenshot --output /tmp/page.png
-chrome-devtools --target <name> screenshot --full-page --output /tmp/page.png
-chrome-devtools --target <name> evaluate "document.title"
-chrome-devtools --target <name> evaluate "document.title" --output /tmp/title.txt
-chrome-devtools --target <name> evaluate "window.location.href = 'https://example.com'" -t # -t/--track-navigation tracks URL changes
-chrome-devtools --target <name> evaluate "alert('hello')" --dialog-action accept
-chrome-devtools --target <name> snapshot   # Accessibility tree — use to understand page structure
-chrome-devtools --target <name> snapshot --output /tmp/tree.txt
+# Evaluate and get return value
+chrome-devtools evaluate "document.title"
+
+# Handle potential dialogs automatically
+chrome-devtools evaluate "alert('hi')" --dialog-action accept
 ```
 
-### Interaction
+## Command Reference
+
+### Navigation
 ```bash
-chrome-devtools --target <name> click "#selector"
-chrome-devtools --target <name> click-at 100 200
-chrome-devtools --target <name> fill "#selector" "value"
-chrome-devtools --target <name> type-text "Hello world" --submit-key Enter
-chrome-devtools --target <name> press-key Enter
-chrome-devtools --target <name> press-key Control+A
-chrome-devtools --target <name> hover ".menu-item"
+chrome-devtools navigate <url> [--viewport WxH] [--mobile] [--device-scale-factor N] [--geolocation lat,lon] [--accuracy M]
+chrome-devtools navigate <url> --extra-headers '{"Authorization":"Bearer ..."}'
+chrome-devtools navigate <url> -o /tmp/result.txt
+chrome-devtools navigate --back
+chrome-devtools navigate --forward
+chrome-devtools navigate --reload
+chrome-devtools new-page <url> [--viewport WxH] [--mobile] [--device-scale-factor N] [--geolocation lat,lon]
+chrome-devtools new-page <url> --extra-headers '{"X-Debug":"1"}'
+chrome-devtools close-page [id_or_index]
+chrome-devtools select-page [id_or_index]
 ```
 
-### Third-party developer tools
+### Emulation
 ```bash
-chrome-devtools list-3p-tools                          # List tools from window.__dtmcp
-chrome-devtools execute-3p-tool <name> '<json-params>' # Execute a custom tool
+chrome-devtools emulate [--viewport WxH] [--mobile] [--device-scale-factor N] [--geolocation lat,lon] [--accuracy M]
+chrome-devtools emulate --clear-all
+chrome-devtools emulate --clear-viewport
+chrome-devtools emulate --clear-geolocation
 ```
 
 ### Utilities
 ```bash
 chrome-devtools --target <name> wait-for "Success" --timeout 10000
-chrome-devtools --target <name> resize 1280 720
+chrome-devtools list-pages
 ```
 
-## Global flags & Environment Variables
-
-| Flag / Env Var | Description |
-|------|-------------|
-| `--target <name>` | Target page by friendly name or raw Chrome target ID |
-| `--page <index>` | Target page by index (for quick one-offs) |
-| `--json` | Machine-readable JSON output (includes `navigated_to` and `error_code`) |
-| `--ws-endpoint <url>` | Explicit WebSocket endpoint (overrides auto-connect) — env: `CHROME_WS_ENDPOINT` |
-| `--user-data-dir <path>` | Custom Chrome profile directory — env: `CHROME_USER_DATA_DIR` |
-| `--channel <ch>` | Chrome channel: stable / beta / canary / dev — env: `CHROME_CHANNEL` |
-| `DAEMON_WAIT_TIMEOUT_SECS` | Env var: Max seconds to wait for a daemon to spawn (default: 5) |
-| `DAEMON_IDLE_TIMEOUT_SECS` | Env var: Max idle seconds before daemon terminates (default: 300) |
-
-## Typical task pattern
-
-1. `list-pages` — see what tabs are open
-2. `navigate <url>` — go to target, **note the `[target:name]`**
-3. `--target name snapshot` — understand the page structure (accessibility tree is compact and token-efficient vs. a screenshot)
-4. `--target name click` / `fill` / `type-text` / `press-key` — interact
-5. `--target name evaluate` — extract data or verify state
-6. `--target name screenshot --output /tmp/result.png` — capture final state if needed
-
-Use `snapshot` before `screenshot` when trying to understand page structure — it returns text, not an image, and costs far fewer tokens.
-
-## Daemon behavior
-
-The binary automatically manages a background daemon that holds a persistent WebSocket connection to Chrome. Chrome prompts for DevTools access once; all subsequent commands reuse the connection silently. No manual daemon management is needed.
-
-To stop it manually: `pkill -f __daemon__`
+### Third-party Developer Tools
+```bash
+chrome-devtools list-3p-tools
+chrome-devtools execute-3p-tool <name> '<json-params>'
+```
diff --git a/src/cdp.rs b/src/cdp.rs
index 14e5a93..ff9a2a9 100644
--- a/src/cdp.rs
+++ b/src/cdp.rs
@@ -82,6 +82,7 @@ pub struct CdpClient {
 
 const MAX_BUFFERED_EVENTS: usize = 1000;
 
+/// Metadata for a Chrome target (page, worker, etc.).
 #[derive(Debug, Clone)]
 pub struct TargetInfo {
     pub target_id: String,
@@ -92,6 +93,7 @@ pub struct TargetInfo {
 }
 
 impl CdpClient {
+    /// Connect to Chrome via WebSocket and return a CDP client.
     pub async fn connect(ws_url: &str) -> Result<Self> {
         let (ws, _) = connect_async(ws_url)
             .await
@@ -310,6 +312,7 @@ impl CdpClient {
         }
     }
 
+    /// Read the next text message from the WebSocket, skipping non-text frames.
     pub async fn read_text(&mut self) -> Result<String> {
         loop {
             match self.read.next().await {
@@ -324,6 +327,7 @@ impl CdpClient {
 
     // ── Target domain helpers ──
 
+    /// List all open page targets.
     pub async fn get_page_targets(&mut self) -> Result<Vec<TargetInfo>> {
         let result = self.send("Target.getTargets", json!({})).await?;
         let targets = result["targetInfos"].as_array().ok_or_else(|| {
@@ -352,6 +356,7 @@ impl CdpClient {
         Ok(pages)
     }
 
+    /// Attach to a target and return the session ID for subsequent commands.
     pub async fn attach_to_target(&mut self, target_id: &str) -> Result<String> {
         let result = self
             .send(
@@ -365,18 +370,21 @@ impl CdpClient {
             .ok_or_else(|| anyhow!("No sessionId in attachToTarget response"))
     }
 
+    /// Detach from a target session.
     pub async fn detach_from_target(&mut self, session_id: &str) -> Result<()> {
         self.send("Target.detachFromTarget", json!({"sessionId": session_id}))
             .await?;
         Ok(())
     }
 
+    /// Bring a target to the foreground.
     pub async fn activate_target(&mut self, target_id: &str) -> Result<()> {
         self.send("Target.activateTarget", json!({"targetId": target_id}))
             .await?;
         Ok(())
     }
 
+    /// Create a new page target and return its target ID.
     pub async fn create_target(&mut self, url: &str) -> Result<String> {
         let result = self
             .send("Target.createTarget", json!({"url": url}))
@@ -387,6 +395,7 @@ impl CdpClient {
             .ok_or_else(|| anyhow!("No targetId in createTarget response"))
     }
 
+    /// Close a target by its target ID.
     pub async fn close_target(&mut self, target_id: &str) -> Result<()> {
         self.send("Target.closeTarget", json!({"targetId": target_id}))
             .await?;
diff --git a/src/commands/emulation.rs b/src/commands/emulation.rs
new file mode 100644
index 0000000..4616d73
--- /dev/null
+++ b/src/commands/emulation.rs
@@ -0,0 +1,144 @@
+use anyhow::{anyhow, Result};
+use serde_json::json;
+
+use crate::cdp::CdpClient;
+use crate::result::CommandResult;
+
+/// Combined emulation parameters for the `emulate` command.
+pub struct EmulateParams {
+    pub viewport: Option<String>,
+    pub device_scale_factor: Option<f64>,
+    pub mobile: bool,
+    pub geolocation: Option<String>,
+    pub accuracy: Option<f64>,
+    pub clear_viewport: bool,
+    pub clear_geolocation: bool,
+    pub clear_all: bool,
+}
+
+impl EmulateParams {
+    /// Validate cross-field constraints before applying emulation.
+    pub fn validate(&self) -> Result<()> {
+        if let Some(dsf) = self.device_scale_factor {
+            if !dsf.is_finite() || dsf <= 0.0 {
+                anyhow::bail!("device-scale-factor must be a positive finite value");
+            }
+        }
+        if let Some(acc) = self.accuracy {
+            if acc.is_sign_negative() || !acc.is_finite() {
+                anyhow::bail!("accuracy must be a non-negative finite value");
+            }
+        }
+        if self.accuracy.is_some() && self.geolocation.is_none() {
+            anyhow::bail!("--accuracy requires --geolocation");
+        }
+        if self.mobile && self.viewport.is_none() {
+            anyhow::bail!("--mobile requires --viewport");
+        }
+        if self.device_scale_factor.is_some() && self.viewport.is_none() {
+            anyhow::bail!("--device-scale-factor requires --viewport");
+        }
+        Ok(())
+    }
+
+    /// Returns true if any flag that triggers emulation is set.
+    pub fn has_emulation(&self) -> bool {
+        self.viewport.is_some()
+            || self.geolocation.is_some()
+            || self.device_scale_factor.is_some()
+            || self.mobile
+            || self.clear_all
+            || self.clear_viewport
+            || self.clear_geolocation
+    }
+}
+
+/// Execute the unified emulation command.
+pub async fn emulate(
+    client: &mut CdpClient,
+    session_id: &str,
+    params: EmulateParams,
+) -> Result<CommandResult> {
+    let mut actions = Vec::new();
+
+    // 1. Handle clearing
+    if params.clear_all || params.clear_viewport {
+        client
+            .send_to_target(session_id, "Emulation.clearDeviceMetricsOverride", json!({}))
+            .await?;
+        actions.push("Viewport cleared".to_string());
+    }
+
+    if params.clear_all || params.clear_geolocation {
+        client
+            .send_to_target(session_id, "Emulation.clearGeolocationOverride", json!({}))
+            .await?;
+        actions.push("Geolocation cleared".to_string());
+    }
+
+    // 2. Handle setting viewport
+    if let Some(viewport_str) = params.viewport {
+        let viewport_lower = viewport_str.to_lowercase();
+        let parts: Vec<&str> = viewport_lower.split('x').collect();
+        if parts.len() != 2 {
+            anyhow::bail!("Viewport must be in WxH format (e.g. 1280x720)");
+        }
+        let w: u32 = parts[0].trim().parse().map_err(|_| anyhow!("Invalid width: {}", parts[0]))?;
+        let h: u32 = parts[1].trim().parse().map_err(|_| anyhow!("Invalid height: {}", parts[1]))?;
+        if w == 0 {
+            anyhow::bail!("Invalid width: {} (must be > 0)", w);
+        }
+        if h == 0 {
+            anyhow::bail!("Invalid height: {} (must be > 0)", h);
+        }
+        let dsf = params.device_scale_factor.unwrap_or(1.0);
+
+        client
+            .send_to_target(
+                session_id,
+                "Emulation.setDeviceMetricsOverride",
+                json!({
+                    "width": w,
+                    "height": h,
+                    "deviceScaleFactor": dsf,
+                    "mobile": params.mobile,
+                }),
+            )
+            .await?;
+        actions.push(format!("Viewport set to {}x{} (scale: {}, mobile: {})", w, h, dsf, params.mobile));
+    }
+
+    // 3. Handle setting geolocation
+    if let Some(geo_str) = params.geolocation {
+        let parts: Vec<&str> = geo_str.split(',').collect();
+        if parts.len() != 2 {
+            anyhow::bail!("Geolocation must be in lat,lon format (e.g. 37.77,-122.41)");
+        }
+        let lat: f64 = parts[0].trim().parse().map_err(|_| anyhow!("Invalid latitude: {}", parts[0]))?;
+        let lon: f64 = parts[1].trim().parse().map_err(|_| anyhow!("Invalid longitude: {}", parts[1]))?;
+        let acc = params.accuracy.unwrap_or(100.0);
+
+        if !(-90.0..=90.0).contains(&lat) {
+            anyhow::bail!("latitude must be between -90 and 90");
+        }
+        if !(-180.0..=180.0).contains(&lon) {
+            anyhow::bail!("longitude must be between -180 and 180");
+        }
+
+        client
+            .send_to_target(
+                session_id,
+                "Emulation.setGeolocationOverride",
+                json!({ "latitude": lat, "longitude": lon, "accuracy": acc }),
+            )
+            .await?;
+        actions.push(format!("Geolocation set to {}, {} (acc: {}m)", lat, lon, acc));
+    }
+
+    // 4. If no specific action taken, return error (getters removed due to CDP limitations)
+    if actions.is_empty() {
+        anyhow::bail!("No emulation action specified (use --viewport, --geolocation, or --clear flags)");
+    }
+
+    Ok(CommandResult::output(actions.join(", ")))
+}
diff --git a/src/commands/evaluate.rs b/src/commands/evaluate.rs
index c1a8bc5..6fd74ed 100644
--- a/src/commands/evaluate.rs
+++ b/src/commands/evaluate.rs
@@ -4,6 +4,7 @@ use serde_json::json;
 use crate::cdp::CdpClient;
 use crate::result::CommandResult;
 
+/// Evaluate a JavaScript expression in the page and return the result.
 pub async fn evaluate(
     client: &mut CdpClient,
     session_id: &str,
diff --git a/src/commands/executor.rs b/src/commands/executor.rs
index 4293202..ec30358 100644
--- a/src/commands/executor.rs
+++ b/src/commands/executor.rs
@@ -7,23 +7,64 @@ use crate::friendly;
 use crate::protocol::DaemonRequest;
 use crate::result::CommandResult;
 
+/// Known arguments for each command. Used to detect and report unknown arguments.
+pub fn known_args(cmd: &str) -> &'static [&'static str] {
+    match cmd {
+        "list-pages" => &[],
+        "new-page" => &["url", "viewport", "device_scale_factor", "mobile", "geolocation", "accuracy", "extra_headers"],
+        "close-page" => &["id_or_index"],
+        "select-page" => &["id_or_index"],
+        "navigate" => &["url", "back", "forward", "reload", "extra_headers", "viewport", "device_scale_factor", "mobile", "geolocation", "accuracy", "clear_all", "output"],
+        "screenshot" => &["output", "format", "full_page"],
+        "evaluate" => &["expression", "dialog_action", "output", "track_navigation"],
+        "click" => &["selector"],
+        "click-at" => &["x", "y"],
+        "fill" => &["selector", "value"],
+        "type-text" => &["text", "submit_key"],
+        "press-key" => &["key"],
+        "hover" => &["selector"],
+        "snapshot" => &["output"],
+        "emulate" => &["viewport", "device_scale_factor", "mobile", "geolocation", "accuracy", "clear_viewport", "clear_geolocation", "clear_all"],
+        "wait-for" => &["text", "timeout"],
+        "list-3p-tools" => &[],
+        "execute-3p-tool" => &["name", "params"],
+        _ => &[],
+    }
+}
+
+/// Check for unknown arguments and return an error message if any are found.
+fn validate_args(cmd: &str, args: &serde_json::Value) -> Result<()> {
+    let known = known_args(cmd);
+    if let Some(obj) = args.as_object() {
+        let unknown: Vec<&String> = obj.keys().filter(|k| {
+            let key = k.as_str();
+            // dialog_action is handled globally for all page-level commands
+            if key == "dialog_action" && !is_browser_level(cmd) {
+                return false;
+            }
+            !known.contains(&key)
+        }).collect();
+        if !unknown.is_empty() {
+            let unknown_names: Vec<&str> = unknown.iter().map(|s| s.as_str()).collect();
+            bail!(
+                "Unknown argument(s) for '{}': {}. Expected: {}",
+                cmd,
+                unknown_names.join(", "),
+                known.join(", ")
+            );
+        }
+    }
+    Ok(())
+}
+
 /// Whether a command operates at the browser level (no page session needed).
 fn is_browser_level(cmd: &str) -> bool {
     matches!(
         cmd,
-        "list-pages" | "new-page" | "close-page" | "select-page"
+        "list-pages" | "new-page"
     )
 }
 
-/// Extract a page index from request args, validating that it's present and fits usize.
-fn parse_page_index(args: &serde_json::Value) -> Result<usize> {
-    args.get("index")
-        .and_then(|v| v.as_u64())
-        .ok_or(anyhow!("index required"))?
-        .try_into()
-        .map_err(|_| anyhow!("index too large"))
-}
-
 /// Execute a single command from a [`DaemonRequest`].
 ///
 /// Handles target resolution, session attachment, dialog configuration,
@@ -37,6 +78,8 @@ pub async fn execute_command(client: &mut CdpClient, req: &DaemonRequest) -> Res
     let args = &req.args;
     let cmd = req.command.as_str();
 
+    validate_args(cmd, args)?;
+
     if is_browser_level(cmd) {
         return match cmd {
             "list-pages" => commands::pages::list_pages(client, req.json_output).await,
@@ -45,23 +88,70 @@ pub async fn execute_command(client: &mut CdpClient, req: &DaemonRequest) -> Res
                     .get("url")
                     .and_then(|v| v.as_str())
                     .ok_or(anyhow!("url required"))?;
-                commands::pages::new_page(client, url).await
-            }
-            "close-page" => {
-                let index = parse_page_index(args)?;
-                commands::pages::close_page(client, index).await
-            }
-            "select-page" => {
-                let index = parse_page_index(args)?;
-                commands::pages::select_page(client, index).await
+
+                let viewport = args.get("viewport").and_then(|v| v.as_str());
+                let geolocation = args.get("geolocation").and_then(|v| v.as_str());
+
+                let params = commands::emulation::EmulateParams {
+                    viewport: viewport.map(|s| s.to_string()),
+                    device_scale_factor: args.get("device_scale_factor").and_then(|v| v.as_f64()),
+                    mobile: args.get("mobile").and_then(|v| v.as_bool()).unwrap_or(false),
+                    geolocation: geolocation.map(|s| s.to_string()),
+                    accuracy: args.get("accuracy").and_then(|v| v.as_f64()),
+                    clear_viewport: false,
+                    clear_geolocation: false,
+                    clear_all: false,
+                };
+                params.validate()?;
+
+                let params = if params.has_emulation() {
+                    Some(params)
+                } else {
+                    None
+                };
+
+                commands::pages::new_page(client, url, params, args.get("extra_headers").and_then(|v| v.as_str())).await
             }
             _ => unreachable!(),
         };
     }
 
     // Page-level: resolve and attach to target
-    let target = client.resolve_page(req.target.as_deref(), req.page).await?;
+    let (target_id_arg, page_idx_arg) = if cmd == "close-page" || cmd == "select-page" {
+        match args.get("id_or_index") {
+            Some(v) if v.is_string() => {
+                let s = v.as_str().unwrap();
+                if let Ok(idx) = s.parse::<usize>() {
+                    (None, Some(idx))
+                } else {
+                    (Some(s), None)
+                }
+            }
+            Some(v) if v.is_number() => {
+                let idx = v.as_u64()
+                    .ok_or_else(|| anyhow!("invalid numeric id_or_index: must be a non-negative integer"))?;
+                let idx_usize = usize::try_from(idx)
+                    .map_err(|_| anyhow!("index too large"))?;
+                (None, Some(idx_usize))
+            }
+            _ => (req.target.as_deref(), req.page),
+        }
+    } else {
+        (req.target.as_deref(), req.page)
+    };
+
+    let target = client.resolve_page(target_id_arg, page_idx_arg).await?;
     let target_id = target.target_id.clone();
+
+    // Special case for commands that target a page but don't need a session
+    if cmd == "close-page" || cmd == "select-page" {
+        return match cmd {
+            "close-page" => commands::pages::close_page(client, &target_id).await,
+            "select-page" => commands::pages::select_page(client, &target_id).await,
+            _ => unreachable!(),
+        };
+    }
+
     let session_id = client.attach_to_target(&target_id).await?;
 
     let result = inner_execute(client, &session_id, req).await;
@@ -99,6 +189,27 @@ async fn inner_execute(
 
     match cmd {
         "navigate" => {
+            // Apply emulation before navigation if requested
+            let viewport = args.get("viewport").and_then(|v| v.as_str());
+            let geolocation = args.get("geolocation").and_then(|v| v.as_str());
+            let clear_all = args.get("clear_all").and_then(|v| v.as_bool()).unwrap_or(false);
+
+            let params = commands::emulation::EmulateParams {
+                viewport: viewport.map(|s| s.to_string()),
+                device_scale_factor: args.get("device_scale_factor").and_then(|v| v.as_f64()),
+                mobile: args.get("mobile").and_then(|v| v.as_bool()).unwrap_or(false),
+                geolocation: geolocation.map(|s| s.to_string()),
+                accuracy: args.get("accuracy").and_then(|v| v.as_f64()),
+                clear_viewport: false,
+                clear_geolocation: false,
+                clear_all,
+            };
+            params.validate()?;
+
+            if params.has_emulation() {
+                commands::emulation::emulate(client, session_id, params).await?;
+            }
+
             commands::navigate::navigate(
                 client,
                 session_id,
@@ -110,6 +221,7 @@ async fn inner_execute(
                 args.get("reload")
                     .and_then(|v| v.as_bool())
                     .unwrap_or(false),
+                args.get("extra_headers").and_then(|v| v.as_str()),
                 args.get("output").and_then(|v| v.as_str()),
             )
             .await
@@ -189,19 +301,20 @@ async fn inner_execute(
             )
             .await
         }
-        "resize" => match (
-            args.get("width").and_then(|v| v.as_u64()),
-            args.get("height").and_then(|v| v.as_u64()),
-        ) {
-            (Some(w), Some(h)) => match (w.try_into(), h.try_into()) {
-                (Ok(w_val), Ok(h_val)) => {
-                    commands::pages::resize(client, session_id, w_val, h_val).await
-                }
-                (Err(_), _) => bail!("width too large"),
-                (_, Err(_)) => bail!("height too large"),
-            },
-            _ => bail!("width and height required"),
-        },
+        "emulate" => {
+            let params = commands::emulation::EmulateParams {
+                viewport: args.get("viewport").and_then(|v| v.as_str()).map(|s| s.to_string()),
+                device_scale_factor: args.get("device_scale_factor").and_then(|v| v.as_f64()),
+                mobile: args.get("mobile").and_then(|v| v.as_bool()).unwrap_or(false),
+                geolocation: args.get("geolocation").and_then(|v| v.as_str()).map(|s| s.to_string()),
+                accuracy: args.get("accuracy").and_then(|v| v.as_f64()),
+                clear_viewport: args.get("clear_viewport").and_then(|v| v.as_bool()).unwrap_or(false),
+                clear_geolocation: args.get("clear_geolocation").and_then(|v| v.as_bool()).unwrap_or(false),
+                clear_all: args.get("clear_all").and_then(|v| v.as_bool()).unwrap_or(false),
+            };
+            params.validate()?;
+            commands::emulation::emulate(client, session_id, params).await
+        }
         "wait-for" => match args.get("text").and_then(|v| v.as_str()) {
             Some(text) => {
                 let timeout = args
diff --git a/src/commands/input.rs b/src/commands/input.rs
index cb1522c..5a2aaad 100644
--- a/src/commands/input.rs
+++ b/src/commands/input.rs
@@ -78,6 +78,7 @@ async fn dispatch_mouse(
     Ok(())
 }
 
+/// Click an element identified by CSS selector.
 pub async fn click(
     client: &mut CdpClient,
     session_id: &str,
@@ -190,6 +191,7 @@ async fn wait_for_navigation(client: &mut CdpClient, session_id: &str) -> Result
     Ok(())
 }
 
+/// Click at absolute page coordinates (x, y).
 pub async fn click_at(
     client: &mut CdpClient,
     session_id: &str,
@@ -212,6 +214,7 @@ pub async fn click_at(
         .with_navigated_to_if_changed(new_url, initial_url))
 }
 
+/// Hover over an element identified by CSS selector.
 pub async fn hover(
     client: &mut CdpClient,
     session_id: &str,
@@ -225,6 +228,7 @@ pub async fn hover(
         .with_navigated_to_if_changed(new_url, initial_url))
 }
 
+/// Fill an input field identified by CSS selector with the given value.
 pub async fn fill(
     client: &mut CdpClient,
     session_id: &str,
@@ -351,6 +355,7 @@ if res_val == "not_found" {
     )
 }
 
+/// Insert text at the current focus point, optionally pressing a submit key.
 pub async fn type_text(
     client: &mut CdpClient,
     session_id: &str,
@@ -374,6 +379,7 @@ pub async fn type_text(
     .with_navigated_to_if_changed(new_url, initial_url))
 }
 
+/// Press a key or key combination (e.g. "Enter", "Ctrl+A").
 pub async fn press_key(
     client: &mut CdpClient,
     session_id: &str,
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index dc06b80..20fcdc0 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -1,3 +1,4 @@
+pub mod emulation;
 pub mod evaluate;
 pub mod executor;
 pub mod input;
diff --git a/src/commands/navigate.rs b/src/commands/navigate.rs
index b4ff6cd..8c80c2c 100644
--- a/src/commands/navigate.rs
+++ b/src/commands/navigate.rs
@@ -1,9 +1,11 @@
-use anyhow::{bail, Result};
+use anyhow::{anyhow, bail, Result};
 use serde_json::json;
 
 use crate::cdp::CdpClient;
+use crate::constants::NAVIGATION_TIMEOUT_MS;
 use crate::result::CommandResult;
 
+/// Navigate to a URL, go back/forward in history, or reload the page.
 pub async fn navigate(
     client: &mut CdpClient,
     session_id: &str,
@@ -11,33 +13,56 @@ pub async fn navigate(
     back: bool,
     forward: bool,
     reload: bool,
+    extra_headers: Option<&str>,
     output: Option<&str>,
 ) -> Result<CommandResult> {
-    if back {
-        return go_back(client, session_id, output).await;
+    // Validate navigation intent before mutating session state
+    let intent_count = [back, forward, reload, url.is_some()].iter().filter(|&&b| b).count();
+    if intent_count == 0 {
+        bail!("URL required (or use --back, --forward, --reload)");
     }
-    if forward {
-        return go_forward(client, session_id, output).await;
-    }
-    if reload {
-        return do_reload(client, session_id, output).await;
+    if intent_count > 1 {
+        bail!("Conflicting navigation intents: only one of URL, --back, --forward, or --reload can be specified");
     }
 
-    let url =
-        url.ok_or_else(|| anyhow::anyhow!("URL required (or use --back, --forward, --reload)"))?;
+    super::pages::apply_extra_headers(client, session_id, extra_headers).await?;
 
-    let result = client
-        .send_to_target(session_id, "Page.navigate", json!({"url": url}))
-        .await?;
+    let navigate_result = async {
+        if back {
+            return go_back(client, session_id, output).await;
+        }
+        if forward {
+            return go_forward(client, session_id, output).await;
+        }
+        if reload {
+            return do_reload(client, session_id, output).await;
+        }
+
+        let url = url.unwrap(); // safe: validated above
+
+        let result = client
+            .send_to_target(session_id, "Page.navigate", json!({"url": url}))
+            .await?;
 
-    if let Some(err) = result.get("errorText").and_then(|v| v.as_str()) {
-        bail!("Navigation error: {err}");
+        if let Some(err) = result.get("errorText").and_then(|v| v.as_str()) {
+            bail!("Navigation error: {err}");
+        }
+
+        wait_for_load(client, session_id, NAVIGATION_TIMEOUT_MS).await?;
+        let result =
+            CommandResult::output(format!("Navigated to {url}")).with_navigated_to(url.to_string());
+        Ok(result.save_output(output).await?)
     }
+    .await;
 
-    wait_for_load(client, session_id, 30_000).await?;
-    let result =
-        CommandResult::output(format!("Navigated to {url}")).with_navigated_to(url.to_string());
-    Ok(result.save_output(output).await?)
+    // Only clear headers that this invocation applied.
+    if extra_headers.is_some() {
+        if let Err(e) = super::pages::clear_extra_headers(client, session_id).await {
+            eprintln!("Warning: failed to clear extra headers: {e}");
+        }
+    }
+
+    navigate_result
 }
 
 async fn go_back(
@@ -69,7 +94,7 @@ async fn go_back(
         )
         .await?;
 
-    wait_for_load(client, session_id, 30_000).await?;
+    wait_for_load(client, session_id, NAVIGATION_TIMEOUT_MS).await?;
     let url = prev_entry["url"].as_str().unwrap_or("unknown");
     let result = CommandResult::output(format!("Navigated back to {url}"))
         .with_navigated_to(url.to_string());
@@ -105,7 +130,7 @@ async fn go_forward(
         )
         .await?;
 
-    wait_for_load(client, session_id, 30_000).await?;
+    wait_for_load(client, session_id, NAVIGATION_TIMEOUT_MS).await?;
     let url = next_entry["url"].as_str().unwrap_or("unknown");
     let result = CommandResult::output(format!("Navigated forward to {url}"))
         .with_navigated_to(url.to_string());
@@ -120,21 +145,21 @@ async fn do_reload(
     client
         .send_to_target(session_id, "Page.reload", json!({}))
         .await?;
-    wait_for_load(client, session_id, 30_000).await?;
+    wait_for_load(client, session_id, NAVIGATION_TIMEOUT_MS).await?;
     let url = client.current_url(session_id).await?;
-    let result = CommandResult::output("Reloaded page".to_string()).with_navigated_to(url.clone());
+    let result = CommandResult::output("Reloaded page".to_string());
     Ok(result.save_output(output).await?.with_navigated_to(url))
 }
 
-async fn wait_for_load(client: &mut CdpClient, session_id: &str, timeout_ms: u64) -> Result<()> {
+/// Poll until document.readyState is "complete" or the timeout expires.
+pub async fn wait_for_load(client: &mut CdpClient, session_id: &str, timeout_ms: u64) -> Result<()> {
     let deadline = tokio::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
 
     tokio::time::sleep(std::time::Duration::from_millis(100)).await;
 
     loop {
         if tokio::time::Instant::now() > deadline {
-            eprintln!("Warning: page did not reach readyState=complete within {timeout_ms}ms");
-            return Ok(());
+            anyhow::bail!("Timeout ({timeout_ms}ms) waiting for page readyState=complete");
         }
 
         let result = client
@@ -148,9 +173,21 @@ async fn wait_for_load(client: &mut CdpClient, session_id: &str, timeout_ms: u64
             )
             .await;
 
-        if let Ok(val) = result {
-            if val["result"]["value"].as_str() == Some("complete") {
-                return Ok(());
+        match result {
+            Ok(val) => {
+                if val["result"]["value"].as_str() == Some("complete") {
+                    return Ok(());
+                }
+            }
+            Err(e) => {
+                let msg = e.to_string();
+                if msg.contains("Execution context was destroyed")
+                    || msg.contains("Cannot find context")
+                {
+                    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+                    continue;
+                }
+                return Err(anyhow!("wait_for_load failed for session {session_id}: {e}"));
             }
         }
 
diff --git a/src/commands/pages.rs b/src/commands/pages.rs
index 5202058..404c45b 100644
--- a/src/commands/pages.rs
+++ b/src/commands/pages.rs
@@ -1,11 +1,64 @@
-use anyhow::{anyhow, Result};
+use anyhow::Result;
 use serde_json::json;
 use std::fmt::Write;
 
 use crate::cdp::CdpClient;
+use crate::constants::NAVIGATION_TIMEOUT_MS;
 use crate::friendly;
 use crate::result::CommandResult;
 
+/// Apply extra HTTP headers to a page session via Network.setExtraHTTPHeaders.
+pub async fn apply_extra_headers(
+    client: &mut CdpClient,
+    session_id: &str,
+    extra_headers: Option<&str>,
+) -> Result<()> {
+    if let Some(headers_json) = extra_headers {
+        let headers: serde_json::Value = serde_json::from_str(headers_json)
+            .map_err(|e| anyhow::anyhow!("Invalid --extra-headers JSON: {e}"))?;
+        let headers_obj = headers
+            .as_object()
+            .ok_or_else(|| anyhow::anyhow!("--extra-headers must be a JSON object"))?;
+        let mut converted_headers = serde_json::Map::new();
+        for (k, v) in headers_obj {
+            let val_str = match v {
+                serde_json::Value::String(s) => s.clone(),
+                serde_json::Value::Number(n) => n.to_string(),
+                serde_json::Value::Bool(b) => b.to_string(),
+                _ => anyhow::bail!("Header value for '{}' must be a primitive scalar (string, number, or boolean)", k),
+            };
+            converted_headers.insert(k.clone(), serde_json::Value::String(val_str));
+        }
+        client
+            .send_to_target(session_id, "Network.enable", json!({}))
+            .await?;
+        client
+            .send_to_target(
+                session_id,
+                "Network.setExtraHTTPHeaders",
+                json!({"headers": converted_headers}),
+            )
+            .await?;
+    }
+    Ok(())
+}
+
+/// Clear extra HTTP headers for a page session.
+pub async fn clear_extra_headers(client: &mut CdpClient, session_id: &str) -> Result<()> {
+    client
+        .send_to_target(
+            session_id,
+            "Network.setExtraHTTPHeaders",
+            json!({"headers": {}}),
+        )
+        .await?;
+    let _ = client
+        .send_to_target(session_id, "Network.disable", json!({}))
+        .await;
+    Ok(())
+}
+
+/// List all open page targets with their friendly names, titles, and URLs.
 pub async fn list_pages(client: &mut CdpClient, as_json: bool) -> Result<CommandResult> {
     let pages = client.get_page_targets().await?;
 
@@ -36,60 +89,74 @@ pub async fn list_pages(client: &mut CdpClient, as_json: bool) -> Result<Command
     }
 }
 
-pub async fn new_page(client: &mut CdpClient, url: &str) -> Result<CommandResult> {
-    let target_id = client.create_target(url).await?;
-    Ok(CommandResult::output(format!(
-        "Opened new page: {url} (target: {target_id})"
-    )))
-}
+/// Open a new page, optionally applying emulation and extra headers before navigation.
+pub async fn new_page(
+    client: &mut CdpClient,
+    url: &str,
+    emulation: Option<crate::commands::emulation::EmulateParams>,
+    extra_headers: Option<&str>,
+) -> Result<CommandResult> {
+    if emulation.is_some() || extra_headers.is_some() {
+        // Create blank page so emulation/headers are applied before the real URL loads
+        let target_id = client.create_target("about:blank").await?;
 
-pub async fn close_page(client: &mut CdpClient, index: usize) -> Result<CommandResult> {
-    let pages = client.get_page_targets().await?;
-    let page = pages
-        .get(index)
-        .ok_or_else(|| anyhow!("No page at index {index} (have {} pages)", pages.len()))?;
-    client.close_target(&page.target_id).await?;
-    Ok(CommandResult::output(format!(
-        "Closed page [{index}]: {}",
-        page.url
-    )))
+        let result: Result<()> = async {
+            let session_id = client.attach_to_target(&target_id).await?;
+
+            let inner: Result<()> = async {
+                if let Some(params) = emulation {
+                    crate::commands::emulation::emulate(client, &session_id, params).await?;
+                }
+                apply_extra_headers(client, &session_id, extra_headers).await?;
+                let nav_result = client
+                    .send_to_target(&session_id, "Page.navigate", json!({ "url": url }))
+                    .await?;
+                if let Some(error_text) = nav_result.get("errorText").and_then(|v| v.as_str()) {
+                    anyhow::bail!("Page.navigate failed: {error_text}");
+                }
+                crate::commands::navigate::wait_for_load(client, &session_id, NAVIGATION_TIMEOUT_MS).await?;
+                Ok(())
+            }
+            .await;
+
+            let _ = client.detach_from_target(&session_id).await;
+            inner
+        }
+        .await;
+
+        if let Err(e) = result {
+            let _ = client.close_target(&target_id).await;
+            return Err(e);
+        }
+
+        Ok(CommandResult::output(format!(
+            "Opened new page: {url} (target: {target_id})"
+        )))
+    } else {
+        let target_id = client.create_target(url).await?;
+        Ok(CommandResult::output(format!(
+            "Opened new page: {url} (target: {target_id})"
+        )))
+    }
 }
 
-pub async fn select_page(client: &mut CdpClient, index: usize) -> Result<CommandResult> {
-    let pages = client.get_page_targets().await?;
-    let page = pages
-        .get(index)
-        .ok_or_else(|| anyhow!("No page at index {index} (have {} pages)", pages.len()))?;
-    client.activate_target(&page.target_id).await?;
-    Ok(CommandResult::output(format!(
-        "Activated page [{index}]: {} — {}",
-        page.title, page.url
-    )))
+/// Close a page target by its target ID.
+pub async fn close_page(client: &mut CdpClient, target_id: &str) -> Result<CommandResult> {
+    client.close_target(target_id).await?;
+    let friendly_name = friendly::to_friendly(target_id);
+    Ok(CommandResult::output(format!("Closed page: {friendly_name}")))
 }
 
-pub async fn resize(
-    client: &mut CdpClient,
-    session_id: &str,
-    width: u32,
-    height: u32,
-) -> Result<CommandResult> {
-    client
-        .send_to_target(
-            session_id,
-            "Emulation.setDeviceMetricsOverride",
-            json!({
-                "width": width,
-                "height": height,
-                "deviceScaleFactor": 1,
-                "mobile": false,
-            }),
-        )
-        .await?;
-    Ok(CommandResult::output(format!(
-        "Resized viewport to {width}x{height}"
-    )))
+/// Activate (bring to front) a page target by its target ID.
+pub async fn select_page(client: &mut CdpClient, target_id: &str) -> Result<CommandResult> {
+    client.activate_target(target_id).await?;
+    let friendly_name = friendly::to_friendly(target_id);
+    let mut result = CommandResult::output(format!("Activated page: {friendly_name}"));
+    result.target_id = Some(friendly_name);
+    Ok(result)
 }
 
+/// Wait until the page body contains the given text, or timeout.
 pub async fn wait_for(
     client: &mut CdpClient,
     session_id: &str,
@@ -117,9 +184,21 @@ pub async fn wait_for(
             )
             .await;
 
-        if let Ok(val) = result {
-            if val["result"]["value"].as_bool() == Some(true) {
-                return Ok(CommandResult::output(format!("Found text: {text}")));
+        match result {
+            Ok(val) => {
+                if val["result"]["value"].as_bool() == Some(true) {
+                    return Ok(CommandResult::output(format!("Found text: {text}")));
+                }
+            }
+            Err(e) => {
+                let msg = e.to_string();
+                if msg.contains("Execution context was destroyed")
+                    || msg.contains("Cannot find context")
+                {
+                    tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+                    continue;
+                }
+                return Err(anyhow::anyhow!("wait_for failed for session {session_id}: {e}"));
             }
         }
 
diff --git a/src/commands/screenshot.rs b/src/commands/screenshot.rs
index ea3bfe7..2e8a1fc 100644
--- a/src/commands/screenshot.rs
+++ b/src/commands/screenshot.rs
@@ -5,6 +5,7 @@ use serde_json::json;
 use crate::cdp::CdpClient;
 use crate::result::CommandResult;
 
+/// Capture a screenshot of the current page.
 pub async fn take_screenshot(
     client: &mut CdpClient,
     session_id: &str,
diff --git a/src/commands/snapshot.rs b/src/commands/snapshot.rs
index 677abac..0f9ec02 100644
--- a/src/commands/snapshot.rs
+++ b/src/commands/snapshot.rs
@@ -5,6 +5,7 @@ use std::fmt::Write;
 use crate::cdp::CdpClient;
 use crate::result::CommandResult;
 
+/// Take an accessibility tree snapshot of the current page.
 pub async fn take_snapshot(
     client: &mut CdpClient,
     session_id: &str,
diff --git a/src/commands/third_party.rs b/src/commands/third_party.rs
index 335d148..b275938 100644
--- a/src/commands/third_party.rs
+++ b/src/commands/third_party.rs
@@ -4,6 +4,7 @@ use serde_json::json;
 use crate::cdp::CdpClient;
 use crate::result::CommandResult;
 
+/// List third-party DevTools tools registered via __dtmcp on the page.
 pub async fn list_3p_tools(
     client: &mut CdpClient,
     session_id: &str,
@@ -70,6 +71,7 @@ pub async fn list_3p_tools(
     }
 }
 
+/// Execute a named third-party DevTools tool with optional JSON parameters.
 pub async fn execute_3p_tool(
     client: &mut CdpClient,
     session_id: &str,
diff --git a/src/constants.rs b/src/constants.rs
new file mode 100644
index 0000000..47e7626
--- /dev/null
+++ b/src/constants.rs
@@ -0,0 +1,2 @@
+/// Default timeout for page navigation (30 seconds)
+pub const NAVIGATION_TIMEOUT_MS: u64 = 30_000;
diff --git a/src/lib.rs b/src/lib.rs
index 86777cd..e883e18 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,750 @@
+pub mod browser;
 pub mod cdp;
+pub mod client;
 pub mod commands;
+pub mod constants;
+pub mod daemon;
 pub mod error;
 pub mod friendly;
 pub mod protocol;
 pub mod result;
 pub mod telemetry;
+
+use crate::protocol::DaemonRequest;
+use anyhow::Result;
+use clap::error::ErrorKind;
+use clap::{CommandFactory, Parser, Subcommand};
+use serde_json::json;
+
+#[derive(Parser)]
+#[command(
+    name = "chrome-devtools",
+    version,
+    about = "Chrome DevTools Protocol CLI"
+)]
+pub struct Cli {
+    /// Explicit WebSocket endpoint (skips auto-connect)
+    #[arg(long, global = true, env = "CHROME_WS_ENDPOINT")]
+    pub ws_endpoint: Option<String>,
+
+    /// Chrome user data directory (for auto-connect)
+    #[arg(long, global = true, env = "CHROME_USER_DATA_DIR")]
+    pub user_data_dir: Option<String>,
+
+    /// Chrome channel: stable, beta, canary, dev
+    #[arg(long, global = true, default_value = "stable", env = "CHROME_CHANNEL")]
+    pub channel: String,
+
+    /// Page index for page-level commands (0-based, from list-pages)
+    #[arg(long, short, global = true)]
+    pub page: Option<usize>,
+
+    /// Target ID for page-level commands (stable across calls, from command output)
+    #[arg(long, short, global = true)]
+    pub target: Option<String>,
+
+    /// Output as JSON
+    #[arg(long, global = true)]
+    pub json: bool,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand)]
+pub enum Commands {
+    /// List all open pages/tabs
+    ListPages,
+
+    /// Navigate to a URL, or go back/forward/reload
+    Navigate {
+        /// URL to navigate to
+        url: Option<String>,
+        #[arg(long)]
+        back: bool,
+        #[arg(long)]
+        forward: bool,
+        #[arg(long)]
+        reload: bool,
+        /// Extra HTTP headers as a JSON object (e.g. '{"Authorization":"Bearer token"}')
+        #[arg(long)]
+        extra_headers: Option<String>,
+        /// Set viewport size as WxH (e.g. 1280x720)
+        #[arg(long)]
+        viewport: Option<String>,
+        /// Set device scale factor (default: 1.0)
+        #[arg(long)]
+        device_scale_factor: Option<f64>,
+        /// Emulate mobile device (sets mobile=true in CDP)
+        #[arg(long)]
+        mobile: bool,
+        /// Set geolocation as lat,lon (e.g. 37.77,-122.41)
+        #[arg(long)]
+        geolocation: Option<String>,
+        /// Geolocation accuracy in meters (default: 100)
+        #[arg(long)]
+        accuracy: Option<f64>,
+        /// Clear all emulation overrides
+        #[arg(long)]
+        clear_all: bool,
+        /// Write output to a file instead of stdout
+        #[arg(long, short)]
+        output: Option<String>,
+    },
+
+    /// Open a new page/tab
+    NewPage {
+        /// URL to open
+        url: String,
+        /// Set viewport size as WxH (e.g. 1280x720)
+        #[arg(long)]
+        viewport: Option<String>,
+        /// Set device scale factor (default: 1.0)
+        #[arg(long)]
+        device_scale_factor: Option<f64>,
+        /// Emulate mobile device (sets mobile=true in CDP)
+        #[arg(long)]
+        mobile: bool,
+        /// Set geolocation as lat,lon (e.g. 37.77,-122.41)
+        #[arg(long)]
+        geolocation: Option<String>,
+        /// Geolocation accuracy in meters (default: 100)
+        #[arg(long)]
+        accuracy: Option<f64>,
+        /// Extra HTTP headers as a JSON object (e.g. '{"Authorization":"Bearer token"}')
+        #[arg(long)]
+        extra_headers: Option<String>,
+    },
+
+    /// Close a page/tab
+    ClosePage {
+        /// Target ID, friendly name, or 0-based index
+        id_or_index: Option<String>,
+    },
+
+    /// Bring a page to front
+    SelectPage {
+        /// Target ID, friendly name, or 0-based index
+        id_or_index: Option<String>,
+    },
+
+    /// Take a screenshot
+    Screenshot {
+        /// Save to file path (default: print base64 to stdout)
+        #[arg(long, short)]
+        output: Option<String>,
+        /// Image format: png, jpeg, webp
+        #[arg(long, default_value = "png")]
+        format: String,
+        /// Capture full scrollable page
+        #[arg(long)]
+        full_page: bool,
+    },
+
+    /// Evaluate a JavaScript expression
+    Evaluate {
+        /// JavaScript expression
+        expression: String,
+        /// Handle dialogs while execution: accept, dismiss, or string for prompt
+        #[arg(long)]
+        dialog_action: Option<String>,
+        /// Write output to a file instead of stdout
+        #[arg(long, short)]
+        output: Option<String>,
+        /// Track URL changes caused by this evaluation (adds two extra CDP round-trips)
+        #[arg(long, short = 't')]
+        track_navigation: bool,
+    },
+
+    /// Click an element by CSS selector
+    Click { selector: String },
+
+    /// Click at specific coordinates
+    ClickAt { x: f64, y: f64 },
+
+    /// Fill an input field by CSS selector
+    Fill { selector: String, value: String },
+
+    /// Type text using keyboard (into currently focused element)
+    TypeText {
+        text: String,
+        /// Optional key to press after typing (e.g. Enter)
+        #[arg(long)]
+        submit_key: Option<String>,
+    },
+
+    /// Press a key or key combination (e.g. Enter, Control+A)
+    PressKey { key: String },
+
+    /// Hover over an element by CSS selector
+    Hover { selector: String },
+
+    /// Take an accessibility tree snapshot
+    Snapshot {
+        /// Write output to a file instead of stdout
+        #[arg(long, short)]
+        output: Option<String>,
+    },
+
+    /// Manage page emulation (viewport, geolocation, etc.)
+    Emulate {
+        /// Set viewport size as WxH (e.g. 1280x720)
+        #[arg(long)]
+        viewport: Option<String>,
+        /// Set device scale factor (default: 1.0)
+        #[arg(long)]
+        device_scale_factor: Option<f64>,
+        /// Emulate mobile device (sets mobile=true in CDP)
+        #[arg(long)]
+        mobile: bool,
+        /// Set geolocation as lat,lon (e.g. 37.77,-122.41)
+        #[arg(long)]
+        geolocation: Option<String>,
+        /// Geolocation accuracy in meters (default: 100)
+        #[arg(long)]
+        accuracy: Option<f64>,
+        /// Clear viewport override
+        #[arg(long)]
+        clear_viewport: bool,
+        /// Clear geolocation override
+        #[arg(long)]
+        clear_geolocation: bool,
+        /// Clear all emulation overrides
+        #[arg(long)]
+        clear_all: bool,
+    },
+
+    /// Wait for text to appear on the page
+    WaitFor {
+        text: String,
+        #[arg(long, default_value_t = 30000)]
+        timeout: u64,
+    },
+
+    /// List third-party developer tools exposed by the page
+    #[command(name = "list-3p-tools")]
+    List3pTools,
+
+    /// Execute a third-party developer tool exposed by the page
+    #[command(name = "execute-3p-tool")]
+    Execute3pTool {
+        /// Name of the tool to execute
+        name: String,
+        /// JSON-stringified parameters for the tool
+        params: Option<String>,
+    },
+}
+
+impl Cli {
+    /// Whether this command operates at the browser level (no page session needed).
+    fn is_browser_level(&self) -> bool {
+        matches!(
+            self.command,
+            Commands::ListPages | Commands::NewPage { .. }
+        )
+    }
+
+    /// Get the name of the subcommand as a static string for telemetry logging.
+    fn command_name(&self) -> &'static str {
+        match &self.command {
+            Commands::ListPages => "list-pages",
+            Commands::Navigate { .. } => "navigate",
+            Commands::NewPage { .. } => "new-page",
+            Commands::ClosePage { .. } => "close-page",
+            Commands::SelectPage { .. } => "select-page",
+            Commands::Screenshot { .. } => "screenshot",
+            Commands::Evaluate { .. } => "evaluate",
+            Commands::Click { .. } => "click",
+            Commands::ClickAt { .. } => "click-at",
+            Commands::Fill { .. } => "fill",
+            Commands::TypeText { .. } => "type-text",
+            Commands::PressKey { .. } => "press-key",
+            Commands::Hover { .. } => "hover",
+            Commands::Snapshot { .. } => "snapshot",
+            Commands::Emulate { .. } => "emulate",
+            Commands::WaitFor { .. } => "wait-for",
+            Commands::List3pTools => "list-3p-tools",
+            Commands::Execute3pTool { .. } => "execute-3p-tool",
+        }
+    }
+}
+
+/// Build a DaemonRequest from parsed CLI args.
+fn build_request(cli: &Cli) -> DaemonRequest {
+    let (command, args) = match &cli.command {
+        Commands::ListPages => ("list-pages", json!({})),
+        Commands::Navigate {
+            url,
+            back,
+            forward,
+            reload,
+            extra_headers,
+            viewport,
+            device_scale_factor,
+            mobile,
+            geolocation,
+            accuracy,
+            clear_all,
+            output,
+        } => (
+            "navigate",
+            json!({
+                "url": url,
+                "back": back,
+                "forward": forward,
+                "reload": reload,
+                "extra_headers": extra_headers,
+                "viewport": viewport,
+                "device_scale_factor": device_scale_factor,
+                "mobile": mobile,
+                "geolocation": geolocation,
+                "accuracy": accuracy,
+                "clear_all": clear_all,
+                "output": output
+            }),
+        ),
+        Commands::NewPage {
+            url,
+            viewport,
+            device_scale_factor,
+            mobile,
+            geolocation,
+            accuracy,
+            extra_headers,
+        } => (
+            "new-page",
+            json!({
+                "url": url,
+                "viewport": viewport,
+                "device_scale_factor": device_scale_factor,
+                "mobile": mobile,
+                "geolocation": geolocation,
+                "accuracy": accuracy,
+                "extra_headers": extra_headers
+            }),
+        ),
+        Commands::ClosePage { id_or_index } => (
+            "close-page",
+            json!({ "id_or_index": id_or_index }),
+        ),
+        Commands::SelectPage { id_or_index } => (
+            "select-page",
+            json!({ "id_or_index": id_or_index }),
+        ),
+        Commands::Screenshot {
+            output,
+            format,
+            full_page,
+        } => (
+            "screenshot",
+            json!({"output": output, "format": format, "full_page": full_page}),
+        ),
+        Commands::Evaluate {
+            expression,
+            dialog_action,
+            output,
+            track_navigation,
+        } => (
+            "evaluate",
+            json!({"expression": expression, "dialog_action": dialog_action, "output": output, "track_navigation": track_navigation}),
+        ),
+        Commands::Click { selector } => ("click", json!({"selector": selector})),
+        Commands::ClickAt { x, y } => ("click-at", json!({"x": x, "y": y})),
+        Commands::Fill { selector, value } => {
+            ("fill", json!({"selector": selector, "value": value}))
+        }
+        Commands::TypeText { text, submit_key } => {
+            ("type-text", json!({"text": text, "submit_key": submit_key}))
+        }
+        Commands::PressKey { key } => ("press-key", json!({"key": key})),
+        Commands::Hover { selector } => ("hover", json!({"selector": selector})),
+        Commands::Snapshot { output } => ("snapshot", json!({"output": output})),
+        Commands::Emulate {
+            viewport,
+            device_scale_factor,
+            mobile,
+            geolocation,
+            accuracy,
+            clear_viewport,
+            clear_geolocation,
+            clear_all,
+        } => (
+            "emulate",
+            json!({"viewport": viewport, "device_scale_factor": device_scale_factor, "mobile": mobile, "geolocation": geolocation, "accuracy": accuracy, "clear_viewport": clear_viewport, "clear_geolocation": clear_geolocation, "clear_all": clear_all}),
+        ),
+        Commands::WaitFor { text, timeout } => {
+            ("wait-for", json!({"text": text, "timeout": timeout}))
+        }
+        Commands::List3pTools => ("list-3p-tools", json!({})),
+        Commands::Execute3pTool { name, params } => {
+            ("execute-3p-tool", json!({"name": name, "params": params}))
+        }
+    };
+
+    DaemonRequest {
+        command: command.to_string(),
+        args,
+        page: cli.page,
+        target: cli.target.clone(),
+        json_output: cli.json,
+    }
+}
+
+fn print_output(output: &str, navigated_to: Option<&str>, target_id: Option<&str>) {
+    if !output.is_empty() {
+        print!("{output}");
+        if !output.ends_with('\n') {
+            println!();
+        }
+    }
+    if let Some(navigated_to) = navigated_to {
+        eprintln!("[navigated to: {navigated_to}]");
+    }
+    if let Some(target_id) = target_id {
+        eprintln!("[target: {target_id}]");
+    }
+}
+
+fn print_response(resp: &protocol::DaemonResponse) {
+    if resp.success {
+        print_output(&resp.output, resp.navigated_to.as_deref(), None);
+    } else {
+        eprintln!("error: {}", resp.error);
+        telemetry::shutdown_logger();
+        std::process::exit(resp.error_code.unwrap_or(1) as i32);
+    }
+}
+
+fn print_result(result: &result::CommandResult) {
+    print_output(
+        &result.output,
+        result.navigated_to.as_deref(),
+        result.target_id.as_deref(),
+    );
+}
+
+pub async fn run() -> Result<()> {
+    let cli = match Cli::try_parse() {
+        Ok(c) => c,
+        Err(e) => {
+            if matches!(e.kind(), ErrorKind::DisplayHelp | ErrorKind::DisplayVersion) {
+                e.exit();
+            }
+
+            let err_str = e.render().to_string();
+            let clean_err = err_str.replace("For more information, try '--help'.", "");
+            eprintln!("{}", clean_err.trim_end());
+            println!();
+
+            // Show subcommand-specific help when the error is about a subcommand's args
+            let mut cmd = Cli::command();
+            let sub_name = std::env::args_os()
+                .skip(1)
+                .find_map(|arg| {
+                    let s = arg.to_string_lossy();
+                    if !s.starts_with('-') && cmd.get_subcommands().any(|c| c.get_name() == s) {
+                        Some(s.into_owned())
+                    } else {
+                        None
+                    }
+                });
+            match sub_name {
+                Some(name) => {
+                    if let Some(sub_cmd) = cmd.find_subcommand_mut(&name) {
+                        let _ = sub_cmd.print_help();
+                    } else {
+                        let _ = cmd.print_help();
+                    }
+                }
+                None => {
+                    let _ = cmd.print_help();
+                }
+            }
+            std::process::exit(1);
+        }
+    };
+
+    let ws_url = browser::resolve_ws_url(
+        cli.ws_endpoint.as_deref(),
+        cli.user_data_dir.as_deref(),
+        &cli.channel,
+    )?;
+
+    let request = build_request(&cli);
+
+    // Try daemon first
+    if let Ok(resp) = client::send_to_daemon(&request).await {
+        print_response(&resp);
+        return Ok(());
+    }
+
+    // Daemon not running — spawn it
+    client::spawn_daemon(&ws_url)?;
+    if let Err(e) = client::wait_for_daemon().await {
+        return run_direct_fallback(&cli, &ws_url, &e).await;
+    }
+
+    // Retry via daemon
+    match client::send_to_daemon(&request).await {
+        Ok(resp) => {
+            print_response(&resp);
+            Ok(())
+        }
+        Err(e) => {
+            // Daemon failed — fall back to direct execution
+            run_direct_fallback(&cli, &ws_url, &e).await
+        }
+    }
+}
+
+/// Fall back to direct execution when the daemon is unavailable.
+async fn run_direct_fallback(cli: &Cli, ws_url: &str, error: &anyhow::Error) -> Result<()> {
+    eprintln!("Warning: daemon unavailable ({error}), running directly");
+    let cmd_name = cli.command_name();
+    let start = std::time::Instant::now();
+    let result = run_direct(cli, ws_url).await;
+    let duration = start.elapsed();
+    match &result {
+        Ok(r) => {
+            telemetry::log_command(cmd_name, duration, true, r.error_code);
+            print_result(r);
+        }
+        Err(e) => {
+            let code = e
+                .downcast_ref::<error::CliError>()
+                .map(|ce| ce.code().code());
+            telemetry::log_command(cmd_name, duration, false, code);
+        }
+    }
+    result.map(|_| ())
+}
+
+/// Direct execution without daemon (fallback).
+async fn run_direct(cli: &Cli, ws_url: &str) -> Result<result::CommandResult> {
+    let mut client = cdp::CdpClient::connect(ws_url).await?;
+
+    let is_browser = cli.is_browser_level();
+
+    if is_browser {
+        return match &cli.command {
+            Commands::ListPages => commands::pages::list_pages(&mut client, cli.json).await,
+            Commands::NewPage {
+                url,
+                viewport,
+                device_scale_factor,
+                mobile,
+                geolocation,
+                accuracy,
+                extra_headers,
+            } => {
+                let params = commands::emulation::EmulateParams {
+                    viewport: viewport.clone(),
+                    device_scale_factor: *device_scale_factor,
+                    mobile: *mobile,
+                    geolocation: geolocation.clone(),
+                    accuracy: *accuracy,
+                    clear_viewport: false,
+                    clear_geolocation: false,
+                    clear_all: false,
+                };
+                params.validate()?;
+
+                let params = if params.has_emulation() {
+                    Some(params)
+                } else {
+                    None
+                };
+                commands::pages::new_page(&mut client, url, params, extra_headers.as_deref()).await
+            }
+            _ => unreachable!(),
+        };
+    }
+
+    let (target_id_arg, page_idx_arg) = match &cli.command {
+        Commands::ClosePage { id_or_index } | Commands::SelectPage { id_or_index } => {
+            if let Some(s) = id_or_index {
+                if let Ok(idx) = s.parse::<usize>() {
+                    (None, Some(idx))
+                } else {
+                    (Some(s.as_str()), None)
+                }
+            } else {
+                (cli.target.as_deref(), cli.page)
+            }
+        }
+        _ => (cli.target.as_deref(), cli.page),
+    };
+
+    let target = client.resolve_page(target_id_arg, page_idx_arg).await?;
+    let target_id = target.target_id.clone();
+
+    // Special case for browser-level commands that target a specific page but don't need a session
+    if matches!(cli.command, Commands::ClosePage { .. } | Commands::SelectPage { .. }) {
+        return match &cli.command {
+            Commands::ClosePage { .. } => commands::pages::close_page(&mut client, &target_id).await,
+            Commands::SelectPage { .. } => commands::pages::select_page(&mut client, &target_id).await,
+            _ => unreachable!(),
+        };
+    }
+
+    let session_id = client.attach_to_target(&target_id).await?;
+
+    // Enable Page domain to receive dialog events for proactive rejection
+    client
+        .send_to_target(&session_id, "Page.enable", json!({}))
+        .await?;
+
+    // Extract dialog_action if set (only available on Evaluate command, but
+    // apply it for all commands in direct mode to match daemon behavior)
+    let dialog_action = match &cli.command {
+        Commands::Evaluate { dialog_action, .. } => dialog_action.clone(),
+        _ => None,
+    };
+    client.dialog_action = dialog_action;
+
+    let result = match &cli.command {
+        Commands::Navigate {
+            url,
+            back,
+            forward,
+            reload,
+            extra_headers,
+            viewport,
+            device_scale_factor,
+            mobile,
+            geolocation,
+            accuracy,
+            clear_all,
+            output,
+        } => {
+            let params = commands::emulation::EmulateParams {
+                viewport: viewport.clone(),
+                device_scale_factor: *device_scale_factor,
+                mobile: *mobile,
+                geolocation: geolocation.clone(),
+                accuracy: *accuracy,
+                clear_viewport: false,
+                clear_geolocation: false,
+                clear_all: *clear_all,
+            };
+            params.validate()?;
+
+            // Apply emulation before navigation if requested
+            if params.has_emulation() {
+                commands::emulation::emulate(&mut client, &session_id, params).await?;
+            }
+
+            commands::navigate::navigate(
+                &mut client,
+                &session_id,
+                url.as_deref(),
+                *back,
+                *forward,
+                *reload,
+                extra_headers.as_deref(),
+                output.as_deref(),
+            )
+            .await
+        }
+        Commands::Screenshot {
+            output,
+            format,
+            full_page,
+        } => {
+            commands::screenshot::take_screenshot(
+                &mut client,
+                &session_id,
+                output.as_deref(),
+                format,
+                *full_page,
+            )
+            .await
+        }
+        Commands::Evaluate {
+            expression,
+            dialog_action: _,
+            output,
+            track_navigation,
+        } => {
+            commands::evaluate::evaluate(
+                &mut client,
+                &session_id,
+                expression,
+                cli.json,
+                output.as_deref(),
+                *track_navigation,
+            )
+            .await
+        }
+        Commands::Click { selector } => {
+            commands::input::click(&mut client, &session_id, selector).await
+        }
+        Commands::ClickAt { x, y } => {
+            commands::input::click_at(&mut client, &session_id, *x, *y, None).await
+        }
+        Commands::Fill { selector, value } => {
+            commands::input::fill(&mut client, &session_id, selector, value).await
+        }
+        Commands::TypeText { text, submit_key } => {
+            commands::input::type_text(&mut client, &session_id, text, submit_key.as_deref()).await
+        }
+        Commands::PressKey { key } => {
+            commands::input::press_key(&mut client, &session_id, key).await
+        }
+        Commands::Hover { selector } => {
+            commands::input::hover(&mut client, &session_id, selector).await
+        }
+        Commands::Snapshot { output } => {
+            commands::snapshot::take_snapshot(&mut client, &session_id, cli.json, output.as_deref())
+                .await
+        }
+        Commands::Emulate {
+            viewport,
+            device_scale_factor,
+            mobile,
+            geolocation,
+            accuracy,
+            clear_viewport,
+            clear_geolocation,
+            clear_all,
+        } => {
+            let params = commands::emulation::EmulateParams {
+                viewport: viewport.clone(),
+                device_scale_factor: *device_scale_factor,
+                mobile: *mobile,
+                geolocation: geolocation.clone(),
+                accuracy: *accuracy,
+                clear_viewport: *clear_viewport,
+                clear_geolocation: *clear_geolocation,
+                clear_all: *clear_all,
+            };
+            params.validate()?;
+            commands::emulation::emulate(&mut client, &session_id, params)
+                .await
+        }
+        Commands::WaitFor { text, timeout } => {
+            commands::pages::wait_for(&mut client, &session_id, text, *timeout).await
+        }
+        Commands::List3pTools => {
+            commands::third_party::list_3p_tools(&mut client, &session_id, cli.json).await
+        }
+        Commands::Execute3pTool { name, params } => {
+            commands::third_party::execute_3p_tool(
+                &mut client,
+                &session_id,
+                name,
+                params.as_deref(),
+                cli.json,
+            )
+            .await
+        }
+        _ => unreachable!(),
+    };
+
+    let _ = client.detach_from_target(&session_id).await;
+    let name = friendly::to_friendly(&target_id);
+    result.map(|mut r| {
+        r.target_id = Some(name);
+        r
+    })
+}
diff --git a/src/main.rs b/src/main.rs
index ba4e759..386ec4b 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,210 +1,4 @@
-mod browser;
-mod cdp;
-mod client;
-mod commands;
-mod daemon;
-mod error;
-mod friendly;
-mod protocol;
-mod result;
-mod telemetry;
-
-use crate::error::ErrorCode;
-use crate::protocol::DaemonRequest;
-use anyhow::Result;
-use clap::error::ErrorKind;
-use clap::{CommandFactory, Parser, Subcommand};
-use serde_json::json;
-
-#[derive(Parser)]
-#[command(
-    name = "chrome-devtools",
-    version,
-    about = "Chrome DevTools Protocol CLI"
-)]
-struct Cli {
-    /// Explicit WebSocket endpoint (skips auto-connect)
-    #[arg(long, global = true, env = "CHROME_WS_ENDPOINT")]
-    ws_endpoint: Option<String>,
-
-    /// Chrome user data directory (for auto-connect)
-    #[arg(long, global = true, env = "CHROME_USER_DATA_DIR")]
-    user_data_dir: Option<String>,
-
-    /// Chrome channel: stable, beta, canary, dev
-    #[arg(long, global = true, default_value = "stable", env = "CHROME_CHANNEL")]
-    channel: String,
-
-    /// Page index for page-level commands (0-based, from list-pages)
-    #[arg(long, short, global = true)]
-    page: Option<usize>,
-
-    /// Target ID for page-level commands (stable across calls, from command output)
-    #[arg(long, short, global = true)]
-    target: Option<String>,
-
-    /// Output as JSON
-    #[arg(long, global = true)]
-    json: bool,
-
-    #[command(subcommand)]
-    command: Commands,
-}
-
-#[derive(Subcommand)]
-enum Commands {
-    /// List all open pages/tabs
-    ListPages,
-
-    /// Navigate to a URL, or go back/forward/reload
-    Navigate {
-        /// URL to navigate to
-        url: Option<String>,
-        #[arg(long)]
-        back: bool,
-        #[arg(long)]
-        forward: bool,
-        #[arg(long)]
-        reload: bool,
-        /// Write output to a file instead of stdout
-        #[arg(long, short)]
-        output: Option<String>,
-    },
-
-    /// Open a new page/tab
-    NewPage {
-        /// URL to open
-        url: String,
-    },
-
-    /// Close a page/tab by index
-    ClosePage {
-        /// Page index (from list-pages)
-        index: usize,
-    },
-
-    /// Bring a page to front
-    SelectPage {
-        /// Page index (from list-pages)
-        index: usize,
-    },
-
-    /// Take a screenshot
-    Screenshot {
-        /// Save to file path (default: print base64 to stdout)
-        #[arg(long, short)]
-        output: Option<String>,
-        /// Image format: png, jpeg, webp
-        #[arg(long, default_value = "png")]
-        format: String,
-        /// Capture full scrollable page
-        #[arg(long)]
-        full_page: bool,
-    },
-
-    /// Evaluate a JavaScript expression
-    Evaluate {
-        /// JavaScript expression
-        expression: String,
-        /// Handle dialogs while execution: accept, dismiss, or string for prompt
-        #[arg(long)]
-        dialog_action: Option<String>,
-        /// Write output to a file instead of stdout
-        #[arg(long, short)]
-        output: Option<String>,
-        /// Track URL changes caused by this evaluation (adds two extra CDP round-trips)
-        #[arg(long, short = 't')]
-        track_navigation: bool,
-    },
-
-    /// Click an element by CSS selector
-    Click { selector: String },
-
-    /// Click at specific coordinates
-    ClickAt { x: f64, y: f64 },
-
-    /// Fill an input field by CSS selector
-    Fill { selector: String, value: String },
-
-    /// Type text using keyboard (into currently focused element)
-    TypeText {
-        text: String,
-        /// Optional key to press after typing (e.g. Enter)
-        #[arg(long)]
-        submit_key: Option<String>,
-    },
-
-    /// Press a key or key combination (e.g. Enter, Control+A)
-    PressKey { key: String },
-
-    /// Hover over an element by CSS selector
-    Hover { selector: String },
-
-    /// Take an accessibility tree snapshot
-    Snapshot {
-        /// Write output to a file instead of stdout
-        #[arg(long, short)]
-        output: Option<String>,
-    },
-
-    /// Resize the page viewport
-    Resize { width: u32, height: u32 },
-
-    /// Wait for text to appear on the page
-    WaitFor {
-        text: String,
-        #[arg(long, default_value_t = 30000)]
-        timeout: u64,
-    },
-
-    /// List third-party developer tools exposed by the page
-    List3pTools,
-
-    /// Execute a third-party developer tool exposed by the page
-    Execute3pTool {
-        /// Name of the tool to execute
-        name: String,
-        /// JSON-stringified parameters for the tool
-        params: Option<String>,
-    },
-}
-
-impl Cli {
-    /// Whether this command operates at the browser level (no page session needed).
-    fn is_browser_level(&self) -> bool {
-        matches!(
-            self.command,
-            Commands::ListPages
-                | Commands::NewPage { .. }
-                | Commands::ClosePage { .. }
-                | Commands::SelectPage { .. }
-        )
-    }
-
-    /// Get the name of the subcommand as a static string for telemetry logging.
-    fn command_name(&self) -> &'static str {
-        match &self.command {
-            Commands::ListPages => "list-pages",
-            Commands::Navigate { .. } => "navigate",
-            Commands::NewPage { .. } => "new-page",
-            Commands::ClosePage { .. } => "close-page",
-            Commands::SelectPage { .. } => "select-page",
-            Commands::Screenshot { .. } => "screenshot",
-            Commands::Evaluate { .. } => "evaluate",
-            Commands::Click { .. } => "click",
-            Commands::ClickAt { .. } => "click-at",
-            Commands::Fill { .. } => "fill",
-            Commands::TypeText { .. } => "type-text",
-            Commands::PressKey { .. } => "press-key",
-            Commands::Hover { .. } => "hover",
-            Commands::Snapshot { .. } => "snapshot",
-            Commands::Resize { .. } => "resize",
-            Commands::WaitFor { .. } => "wait-for",
-            Commands::List3pTools => "list-3p-tools",
-            Commands::Execute3pTool { .. } => "execute-3p-tool",
-        }
-    }
-}
+use chrome_devtools_cli::{daemon, error::ErrorCode, telemetry};
 
 #[tokio::main]
 async fn main() {
@@ -228,10 +22,10 @@ async fn main() {
         return;
     }
 
-    let result = run().await;
+    let result = chrome_devtools_cli::run().await;
     telemetry::shutdown_logger();
     if let Err(e) = result {
-        let code = match e.downcast_ref::<error::CliError>() {
+        let code = match e.downcast_ref::<chrome_devtools_cli::error::CliError>() {
             Some(ce) => ce.code().code(),
             None => ErrorCode::Unspecified as u32,
         };
@@ -239,309 +33,3 @@ async fn main() {
         std::process::exit(code as i32);
     }
 }
-
-/// Build a DaemonRequest from parsed CLI args.
-fn build_request(cli: &Cli) -> DaemonRequest {
-    let (command, args) = match &cli.command {
-        Commands::ListPages => ("list-pages", json!({})),
-        Commands::Navigate {
-            url,
-            back,
-            forward,
-            reload,
-            output,
-        } => (
-            "navigate",
-            json!({"url": url, "back": back, "forward": forward, "reload": reload, "output": output}),
-        ),
-        Commands::NewPage { url } => ("new-page", json!({"url": url})),
-        Commands::ClosePage { index } => ("close-page", json!({"index": index})),
-        Commands::SelectPage { index } => ("select-page", json!({"index": index})),
-        Commands::Screenshot {
-            output,
-            format,
-            full_page,
-        } => (
-            "screenshot",
-            json!({"output": output, "format": format, "full_page": full_page}),
-        ),
-        Commands::Evaluate {
-            expression,
-            dialog_action,
-            output,
-            track_navigation,
-        } => (
-            "evaluate",
-            json!({"expression": expression, "dialog_action": dialog_action, "output": output, "track_navigation": track_navigation}),
-        ),
-        Commands::Click { selector } => ("click", json!({"selector": selector})),
-        Commands::ClickAt { x, y } => ("click-at", json!({"x": x, "y": y})),
-        Commands::Fill { selector, value } => {
-            ("fill", json!({"selector": selector, "value": value}))
-        }
-        Commands::TypeText { text, submit_key } => {
-            ("type-text", json!({"text": text, "submit_key": submit_key}))
-        }
-        Commands::PressKey { key } => ("press-key", json!({"key": key})),
-        Commands::Hover { selector } => ("hover", json!({"selector": selector})),
-        Commands::Snapshot { output } => ("snapshot", json!({"output": output})),
-        Commands::Resize { width, height } => ("resize", json!({"width": width, "height": height})),
-        Commands::WaitFor { text, timeout } => {
-            ("wait-for", json!({"text": text, "timeout": timeout}))
-        }
-        Commands::List3pTools => ("list-3p-tools", json!({})),
-        Commands::Execute3pTool { name, params } => {
-            ("execute-3p-tool", json!({"name": name, "params": params}))
-        }
-    };
-
-    DaemonRequest {
-        command: command.to_string(),
-        args,
-        page: cli.page,
-        target: cli.target.clone(),
-        json_output: cli.json,
-    }
-}
-
-fn print_output(output: &str, navigated_to: Option<&str>, target_id: Option<&str>) {
-    if !output.is_empty() {
-        print!("{output}");
-        if !output.ends_with('\n') {
-            println!();
-        }
-    }
-    if let Some(navigated_to) = navigated_to {
-        eprintln!("[navigated to: {navigated_to}]");
-    }
-    if let Some(target_id) = target_id {
-        eprintln!("[target: {target_id}]");
-    }
-}
-
-fn print_response(resp: &protocol::DaemonResponse) {
-    if resp.success {
-        print_output(&resp.output, resp.navigated_to.as_deref(), None);
-    } else {
-        eprintln!("error: {}", resp.error);
-        telemetry::shutdown_logger();
-        std::process::exit(resp.error_code.unwrap_or(1) as i32);
-    }
-}
-
-fn print_result(result: &result::CommandResult) {
-    print_output(
-        &result.output,
-        result.navigated_to.as_deref(),
-        result.target_id.as_deref(),
-    );
-}
-
-async fn run() -> Result<()> {
-    let cli = match Cli::try_parse() {
-        Ok(c) => c,
-        Err(e) => {
-            if matches!(e.kind(), ErrorKind::DisplayHelp | ErrorKind::DisplayVersion) {
-                e.exit();
-            }
-
-            let err_str = e.render().to_string();
-            let clean_err = err_str.replace("For more information, try '--help'.", "");
-            eprintln!("{}", clean_err.trim_end());
-            println!();
-            let mut cmd = Cli::command();
-            let _ = cmd.print_help();
-            std::process::exit(1);
-        }
-    };
-
-    let ws_url = browser::resolve_ws_url(
-        cli.ws_endpoint.as_deref(),
-        cli.user_data_dir.as_deref(),
-        &cli.channel,
-    )?;
-
-    let request = build_request(&cli);
-
-    // Try daemon first
-    if let Ok(resp) = client::send_to_daemon(&request).await {
-        print_response(&resp);
-        return Ok(());
-    }
-
-    // Daemon not running — spawn it
-    client::spawn_daemon(&ws_url)?;
-    if let Err(e) = client::wait_for_daemon().await {
-        return run_direct_fallback(&cli, &ws_url, &e).await;
-    }
-
-    // Retry via daemon
-    match client::send_to_daemon(&request).await {
-        Ok(resp) => {
-            print_response(&resp);
-            Ok(())
-        }
-        Err(e) => {
-            // Daemon failed — fall back to direct execution
-            run_direct_fallback(&cli, &ws_url, &e).await
-        }
-    }
-}
-
-/// Fall back to direct execution when the daemon is unavailable.
-async fn run_direct_fallback(cli: &Cli, ws_url: &str, error: &anyhow::Error) -> Result<()> {
-    eprintln!("Warning: daemon unavailable ({error}), running directly");
-    let cmd_name = cli.command_name();
-    let start = std::time::Instant::now();
-    let result = run_direct(cli, ws_url).await;
-    let duration = start.elapsed();
-    match &result {
-        Ok(r) => {
-            telemetry::log_command(cmd_name, duration, true, r.error_code);
-            print_result(r);
-        }
-        Err(e) => {
-            let code = e
-                .downcast_ref::<error::CliError>()
-                .map(|ce| ce.code().code());
-            telemetry::log_command(cmd_name, duration, false, code);
-        }
-    }
-    result.map(|_| ())
-}
-
-/// Direct execution without daemon (fallback).
-async fn run_direct(cli: &Cli, ws_url: &str) -> Result<result::CommandResult> {
-    let mut client = cdp::CdpClient::connect(ws_url).await?;
-
-    let is_browser = cli.is_browser_level();
-
-    if is_browser {
-        return match &cli.command {
-            Commands::ListPages => commands::pages::list_pages(&mut client, cli.json).await,
-            Commands::NewPage { url } => commands::pages::new_page(&mut client, url).await,
-            Commands::ClosePage { index } => commands::pages::close_page(&mut client, *index).await,
-            Commands::SelectPage { index } => {
-                commands::pages::select_page(&mut client, *index).await
-            }
-            _ => unreachable!(),
-        };
-    }
-
-    let target = client.resolve_page(cli.target.as_deref(), cli.page).await?;
-    let target_id = target.target_id.clone();
-    let session_id = client.attach_to_target(&target_id).await?;
-
-    // Enable Page domain to receive dialog events for proactive rejection
-    client
-        .send_to_target(&session_id, "Page.enable", json!({}))
-        .await?;
-
-    // Extract dialog_action if set (only available on Evaluate command, but
-    // apply it for all commands in direct mode to match daemon behavior)
-    let dialog_action = match &cli.command {
-        Commands::Evaluate { dialog_action, .. } => dialog_action.clone(),
-        _ => None,
-    };
-    client.dialog_action = dialog_action;
-
-    let result = match &cli.command {
-        Commands::Navigate {
-            url,
-            back,
-            forward,
-            reload,
-            output,
-        } => {
-            commands::navigate::navigate(
-                &mut client,
-                &session_id,
-                url.as_deref(),
-                *back,
-                *forward,
-                *reload,
-                output.as_deref(),
-            )
-            .await
-        }
-        Commands::Screenshot {
-            output,
-            format,
-            full_page,
-        } => {
-            commands::screenshot::take_screenshot(
-                &mut client,
-                &session_id,
-                output.as_deref(),
-                format,
-                *full_page,
-            )
-            .await
-        }
-        Commands::Evaluate {
-            expression,
-            dialog_action: _,
-            output,
-            track_navigation,
-        } => {
-            commands::evaluate::evaluate(
-                &mut client,
-                &session_id,
-                expression,
-                cli.json,
-                output.as_deref(),
-                *track_navigation,
-            )
-            .await
-        }
-        Commands::Click { selector } => {
-            commands::input::click(&mut client, &session_id, selector).await
-        }
-        Commands::ClickAt { x, y } => {
-            commands::input::click_at(&mut client, &session_id, *x, *y, None).await
-        }
-        Commands::Fill { selector, value } => {
-            commands::input::fill(&mut client, &session_id, selector, value).await
-        }
-        Commands::TypeText { text, submit_key } => {
-            commands::input::type_text(&mut client, &session_id, text, submit_key.as_deref()).await
-        }
-        Commands::PressKey { key } => {
-            commands::input::press_key(&mut client, &session_id, key).await
-        }
-        Commands::Hover { selector } => {
-            commands::input::hover(&mut client, &session_id, selector).await
-        }
-        Commands::Snapshot { output } => {
-            commands::snapshot::take_snapshot(&mut client, &session_id, cli.json, output.as_deref())
-                .await
-        }
-        Commands::Resize { width, height } => {
-            commands::pages::resize(&mut client, &session_id, *width, *height).await
-        }
-        Commands::WaitFor { text, timeout } => {
-            commands::pages::wait_for(&mut client, &session_id, text, *timeout).await
-        }
-        Commands::List3pTools => {
-            commands::third_party::list_3p_tools(&mut client, &session_id, cli.json).await
-        }
-        Commands::Execute3pTool { name, params } => {
-            commands::third_party::execute_3p_tool(
-                &mut client,
-                &session_id,
-                name,
-                params.as_deref(),
-                cli.json,
-            )
-            .await
-        }
-        _ => unreachable!(),
-    };
-
-    let _ = client.detach_from_target(&session_id).await;
-    let name = friendly::to_friendly(&target_id);
-    result.map(|mut r| {
-        r.target_id = Some(name);
-        r
-    })
-}
diff --git a/src/protocol.rs b/src/protocol.rs
index daae7f1..1fed3b3 100644
--- a/src/protocol.rs
+++ b/src/protocol.rs
@@ -25,16 +25,19 @@ pub struct DaemonResponse {
     pub error_code: Option<u32>,
 }
 
+/// Path to the Unix domain socket for daemon communication.
 #[cfg(unix)]
 pub fn socket_path() -> PathBuf {
     std::env::temp_dir().join("chrome-devtools-daemon.sock")
 }
 
+/// Path to the named-pipe address file for daemon communication (Windows).
 #[cfg(windows)]
 pub fn addr_path() -> PathBuf {
     std::env::temp_dir().join("chrome-devtools-daemon.addr")
 }
 
+/// Path to the daemon PID file.
 pub fn pid_path() -> PathBuf {
     std::env::temp_dir().join("chrome-devtools-daemon.pid")
 }
diff --git a/tests/executor_tests.rs b/tests/executor_tests.rs
index ae64ae7..491a255 100644
--- a/tests/executor_tests.rs
+++ b/tests/executor_tests.rs
@@ -3,7 +3,6 @@
 mod tests {
     use chrome_devtools_cli::commands::executor;
     use chrome_devtools_cli::protocol::DaemonRequest;
-    use chrome_devtools_cli::result::CommandResult;
     use serde_json::json;
 
     // TODO: Add mock CdpClient for executor integration tests.
@@ -40,4 +39,35 @@ mod tests {
         };
         assert_eq!(req.command, "click");
     }
+
+    /// Verify that known_args stays in sync with the Clap Command definition.
+    /// This test dynamically inspects the Cli struct's subcommands and asserts
+    /// that known_args matches each subcommand's arguments, guaranteeing they
+    /// never get out of sync when CLI flags are added or removed.
+    #[test]
+    fn test_known_args_sync_with_clap() {
+        use clap::CommandFactory;
+        use chrome_devtools_cli::Cli;
+
+        let cmd = Cli::command();
+        for sub in cmd.get_subcommands() {
+            let name = sub.get_name();
+            let mut expected_args: Vec<String> = sub
+                .get_arguments()
+                .filter(|a| !a.is_global_set() && a.get_id() != "help" && a.get_id() != "version")
+                .map(|a| a.get_id().as_str().replace('-', "_"))
+                .collect();
+            let mut actual_args: Vec<String> = executor::known_args(name)
+                .iter()
+                .map(|s| s.to_string())
+                .collect();
+            expected_args.sort();
+            actual_args.sort();
+            assert_eq!(
+                actual_args, expected_args,
+                "known_args mismatch for command '{}'. Please update known_args in executor.rs.",
+                name
+            );
+        }
+    }
 }