diff --git a/cli/src/commands.rs b/cli/src/commands.rs
index 3cb74aa..9134397 100644
--- a/cli/src/commands.rs
+++ b/cli/src/commands.rs
@@ -2,6 +2,49 @@ use serde_json::{json, Value};
 
 use crate::flags::Flags;
 
+/// Error type for command parsing with contextual information
+#[derive(Debug)]
+pub enum ParseError {
+    /// Command does not exist
+    UnknownCommand { command: String },
+    /// Command exists but subcommand is invalid
+    UnknownSubcommand {
+        subcommand: String,
+        valid_options: &'static [&'static str],
+    },
+    /// Command/subcommand exists but required arguments are missing
+    MissingArguments {
+        context: String,
+        usage: &'static str,
+    },
+}
+
+impl ParseError {
+    pub fn format(&self) -> String {
+        match self {
+            ParseError::UnknownCommand { command } => {
+                format!("Unknown command: {}", command)
+            }
+            ParseError::UnknownSubcommand {
+                subcommand,
+                valid_options,
+            } => {
+                format!(
+                    "Unknown subcommand: {}\nValid options: {}",
+                    subcommand,
+                    valid_options.join(", ")
+                )
+            }
+            ParseError::MissingArguments { context, usage } => {
+                format!(
+                    "Missing arguments for: {}\nUsage: agent-browser {}",
+                    context, usage
+                )
+            }
+        }
+    }
+}
+
 pub fn gen_id() -> String {
     format!(
         "r{}",
@@ -13,9 +56,12 @@ pub fn gen_id() -> String {
     )
 }
 
-pub fn parse_command(args: &[String], flags: &Flags) -> Option<Value> {
+pub fn parse_command(args: &[String], flags: &Flags) -> Result<Value, ParseError> {
     if args.is_empty() {
-        return None;
+        return Err(ParseError::MissingArguments {
+            context: "".to_string(),
+            usage: "<command> [args...]",
+        });
     }
 
     let cmd = args[0].as_str();
@@ -25,64 +71,172 @@ pub fn parse_command(args: &[String], flags: &Flags) -> Option<Value> {
     match cmd {
         // === Navigation ===
         "open" | "goto" | "navigate" => {
-            let url = rest.get(0)?;
+            let url = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: cmd.to_string(),
+                usage: "open <url>",
+            })?;
             let url = if url.starts_with("http") {
                 url.to_string()
             } else {
                 format!("https://{}", url)
             };
-            Some(json!({ "id": id, "action": "navigate", "url": url }))
+            Ok(json!({ "id": id, "action": "navigate", "url": url }))
         }
-        "back" => Some(json!({ "id": id, "action": "back" })),
-        "forward" => Some(json!({ "id": id, "action": "forward" })),
-        "reload" => Some(json!({ "id": id, "action": "reload" })),
+        "back" => Ok(json!({ "id": id, "action": "back" })),
+        "forward" => Ok(json!({ "id": id, "action": "forward" })),
+        "reload" => Ok(json!({ "id": id, "action": "reload" })),
 
         // === Core Actions ===
-        "click" => Some(json!({ "id": id, "action": "click", "selector": rest.get(0)? })),
-        "dblclick" => Some(json!({ "id": id, "action": "dblclick", "selector": rest.get(0)? })),
-        "fill" => Some(json!({ "id": id, "action": "fill", "selector": rest.get(0)?, "value": rest[1..].join(" ") })),
-        "type" => Some(json!({ "id": id, "action": "type", "selector": rest.get(0)?, "text": rest[1..].join(" ") })),
-        "hover" => Some(json!({ "id": id, "action": "hover", "selector": rest.get(0)? })),
-        "focus" => Some(json!({ "id": id, "action": "focus", "selector": rest.get(0)? })),
-        "check" => Some(json!({ "id": id, "action": "check", "selector": rest.get(0)? })),
-        "uncheck" => Some(json!({ "id": id, "action": "uncheck", "selector": rest.get(0)? })),
-        "select" => Some(json!({ "id": id, "action": "select", "selector": rest.get(0)?, "value": rest.get(1)? })),
-        "drag" => Some(json!({ "id": id, "action": "drag", "source": rest.get(0)?, "target": rest.get(1)? })),
-        "upload" => Some(json!({ "id": id, "action": "upload", "selector": rest.get(0)?, "files": &rest[1..] })),
+        "click" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "click".to_string(),
+                usage: "click <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "click", "selector": sel }))
+        }
+        "dblclick" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "dblclick".to_string(),
+                usage: "dblclick <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "dblclick", "selector": sel }))
+        }
+        "fill" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "fill".to_string(),
+                usage: "fill <selector> <text>",
+            })?;
+            Ok(json!({ "id": id, "action": "fill", "selector": sel, "value": rest[1..].join(" ") }))
+        }
+        "type" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "type".to_string(),
+                usage: "type <selector> <text>",
+            })?;
+            Ok(json!({ "id": id, "action": "type", "selector": sel, "text": rest[1..].join(" ") }))
+        }
+        "hover" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "hover".to_string(),
+                usage: "hover <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "hover", "selector": sel }))
+        }
+        "focus" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "focus".to_string(),
+                usage: "focus <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "focus", "selector": sel }))
+        }
+        "check" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "check".to_string(),
+                usage: "check <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "check", "selector": sel }))
+        }
+        "uncheck" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "uncheck".to_string(),
+                usage: "uncheck <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "uncheck", "selector": sel }))
+        }
+        "select" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "select".to_string(),
+                usage: "select <selector> <value>",
+            })?;
+            let val = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "select".to_string(),
+                usage: "select <selector> <value>",
+            })?;
+            Ok(json!({ "id": id, "action": "select", "selector": sel, "value": val }))
+        }
+        "drag" => {
+            let src = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "drag".to_string(),
+                usage: "drag <source> <target>",
+            })?;
+            let tgt = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "drag".to_string(),
+                usage: "drag <source> <target>",
+            })?;
+            Ok(json!({ "id": id, "action": "drag", "source": src, "target": tgt }))
+        }
+        "upload" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "upload".to_string(),
+                usage: "upload <selector> <files...>",
+            })?;
+            Ok(json!({ "id": id, "action": "upload", "selector": sel, "files": &rest[1..] }))
+        }
 
         // === Keyboard ===
-        "press" | "key" => Some(json!({ "id": id, "action": "press", "key": rest.get(0)? })),
-        "keydown" => Some(json!({ "id": id, "action": "keydown", "key": rest.get(0)? })),
-        "keyup" => Some(json!({ "id": id, "action": "keyup", "key": rest.get(0)? })),
+        "press" | "key" => {
+            let key = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "press".to_string(),
+                usage: "press <key>",
+            })?;
+            Ok(json!({ "id": id, "action": "press", "key": key }))
+        }
+        "keydown" => {
+            let key = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "keydown".to_string(),
+                usage: "keydown <key>",
+            })?;
+            Ok(json!({ "id": id, "action": "keydown", "key": key }))
+        }
+        "keyup" => {
+            let key = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "keyup".to_string(),
+                usage: "keyup <key>",
+            })?;
+            Ok(json!({ "id": id, "action": "keyup", "key": key }))
+        }
 
         // === Scroll ===
         "scroll" => {
             let dir = rest.get(0).unwrap_or(&"down");
             let amount = rest.get(1).and_then(|s| s.parse::<i32>().ok()).unwrap_or(300);
-            Some(json!({ "id": id, "action": "scroll", "direction": dir, "amount": amount }))
+            Ok(json!({ "id": id, "action": "scroll", "direction": dir, "amount": amount }))
         }
         "scrollintoview" | "scrollinto" => {
-            Some(json!({ "id": id, "action": "scrollintoview", "selector": rest.get(0)? }))
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "scrollintoview".to_string(),
+                usage: "scrollintoview <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "scrollintoview", "selector": sel }))
         }
 
         // === Wait ===
         "wait" => {
             if let Some(arg) = rest.get(0) {
                 if arg.parse::<u64>().is_ok() {
-                    Some(json!({ "id": id, "action": "wait", "timeout": arg.parse::<u64>().unwrap() }))
+                    Ok(json!({ "id": id, "action": "wait", "timeout": arg.parse::<u64>().unwrap() }))
                 } else {
-                    Some(json!({ "id": id, "action": "wait", "selector": arg }))
+                    Ok(json!({ "id": id, "action": "wait", "selector": arg }))
                 }
             } else {
-                None
+                Err(ParseError::MissingArguments {
+                    context: "wait".to_string(),
+                    usage: "wait <selector|ms>",
+                })
             }
         }
 
         // === Screenshot/PDF ===
         "screenshot" => {
-            Some(json!({ "id": id, "action": "screenshot", "path": rest.get(0), "fullPage": flags.full }))
+            Ok(json!({ "id": id, "action": "screenshot", "path": rest.get(0), "fullPage": flags.full }))
+        }
+        "pdf" => {
+            let path = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "pdf".to_string(),
+                usage: "pdf <path>",
+            })?;
+            Ok(json!({ "id": id, "action": "pdf", "path": path }))
         }
-        "pdf" => Some(json!({ "id": id, "action": "pdf", "path": rest.get(0)? })),
 
         // === Snapshot ===
         "snapshot" => {
@@ -115,244 +269,477 @@ pub fn parse_command(args: &[String], flags: &Flags) -> Option<Value> {
                 }
                 i += 1;
             }
-            Some(cmd)
+            Ok(cmd)
         }
 
         // === Eval ===
-        "eval" => Some(json!({ "id": id, "action": "evaluate", "script": rest.join(" ") })),
+        "eval" => Ok(json!({ "id": id, "action": "evaluate", "script": rest.join(" ") })),
 
         // === Close ===
-        "close" | "quit" | "exit" => Some(json!({ "id": id, "action": "close" })),
+        "close" | "quit" | "exit" => Ok(json!({ "id": id, "action": "close" })),
 
         // === Get ===
-        "get" => match rest.get(0).map(|s| *s) {
-            Some("text") => Some(json!({ "id": id, "action": "gettext", "selector": rest.get(1)? })),
-            Some("html") => Some(json!({ "id": id, "action": "innerhtml", "selector": rest.get(1)? })),
-            Some("value") => Some(json!({ "id": id, "action": "inputvalue", "selector": rest.get(1)? })),
-            Some("attr") => Some(json!({ "id": id, "action": "getattribute", "selector": rest.get(1)?, "attribute": rest.get(2)? })),
-            Some("url") => Some(json!({ "id": id, "action": "url" })),
-            Some("title") => Some(json!({ "id": id, "action": "title" })),
-            Some("count") => Some(json!({ "id": id, "action": "count", "selector": rest.get(1)? })),
-            Some("box") => Some(json!({ "id": id, "action": "boundingbox", "selector": rest.get(1)? })),
-            _ => None,
-        },
+        "get" => parse_get(&rest, &id),
 
         // === Is (state checks) ===
-        "is" => match rest.get(0).map(|s| *s) {
-            Some("visible") => Some(json!({ "id": id, "action": "isvisible", "selector": rest.get(1)? })),
-            Some("enabled") => Some(json!({ "id": id, "action": "isenabled", "selector": rest.get(1)? })),
-            Some("checked") => Some(json!({ "id": id, "action": "ischecked", "selector": rest.get(1)? })),
-            _ => None,
-        },
+        "is" => parse_is(&rest, &id),
 
         // === Find (locators) ===
         "find" => parse_find(&rest, &id),
 
         // === Mouse ===
-        "mouse" => match rest.get(0).map(|s| *s) {
-            Some("move") => {
-                let x = rest.get(1)?.parse::<i32>().ok()?;
-                let y = rest.get(2)?.parse::<i32>().ok()?;
-                Some(json!({ "id": id, "action": "mousemove", "x": x, "y": y }))
-            }
-            Some("down") => {
-                Some(json!({ "id": id, "action": "mousedown", "button": rest.get(1).unwrap_or(&"left") }))
-            }
-            Some("up") => {
-                Some(json!({ "id": id, "action": "mouseup", "button": rest.get(1).unwrap_or(&"left") }))
-            }
-            Some("wheel") => {
-                let dy = rest.get(1).and_then(|s| s.parse::<i32>().ok()).unwrap_or(100);
-                let dx = rest.get(2).and_then(|s| s.parse::<i32>().ok()).unwrap_or(0);
-                Some(json!({ "id": id, "action": "mousewheel", "deltaX": dx, "deltaY": dy }))
-            }
-            _ => None,
-        },
+        "mouse" => parse_mouse(&rest, &id),
 
         // === Set (browser settings) ===
         "set" => parse_set(&rest, &id),
 
         // === Network ===
-        "network" => match rest.get(0).map(|s| *s) {
-            Some("route") => {
-                let url = rest.get(1)?;
-                let abort = rest.iter().any(|&s| s == "--abort");
-                let body_idx = rest.iter().position(|&s| s == "--body");
-                let body = body_idx.and_then(|i| rest.get(i + 1).map(|s| *s));
-                Some(json!({ "id": id, "action": "route", "url": url, "abort": abort, "body": body }))
-            }
-            Some("unroute") => Some(json!({ "id": id, "action": "unroute", "url": rest.get(1) })),
-            Some("requests") => {
-                let clear = rest.iter().any(|&s| s == "--clear");
-                let filter_idx = rest.iter().position(|&s| s == "--filter");
-                let filter = filter_idx.and_then(|i| rest.get(i + 1).map(|s| *s));
-                Some(json!({ "id": id, "action": "requests", "clear": clear, "filter": filter }))
-            }
-            _ => None,
-        },
+        "network" => parse_network(&rest, &id),
 
         // === Storage ===
-        "storage" => match rest.get(0).map(|s| *s) {
-            Some("local") | Some("session") => {
-                let storage_type = rest.get(0)?;
-                let op = rest.get(1).unwrap_or(&"get");
-                let key = rest.get(2);
-                let value = rest.get(3);
-                match *op {
-                    "set" => Some(json!({ "id": id, "action": "storage_set", "type": storage_type, "key": key?, "value": value? })),
-                    "clear" => Some(json!({ "id": id, "action": "storage_clear", "type": storage_type })),
-                    _ => {
-                        let mut cmd = json!({ "id": id, "action": "storage_get", "type": storage_type });
-                        if let Some(k) = key {
-                            cmd.as_object_mut().unwrap().insert("key".to_string(), json!(k));
-                        }
-                        Some(cmd)
-                    }
-                }
-            }
-            _ => None,
-        },
+        "storage" => parse_storage(&rest, &id),
 
         // === Cookies ===
         "cookies" => {
             let op = rest.get(0).unwrap_or(&"get");
             match *op {
                 "set" => {
-                    let name = rest.get(1)?;
-                    let value = rest.get(2)?;
-                    Some(json!({ "id": id, "action": "cookies_set", "cookies": [{ "name": name, "value": value }] }))
+                    let name = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                        context: "cookies set".to_string(),
+                        usage: "cookies set <name> <value>",
+                    })?;
+                    let value = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                        context: "cookies set".to_string(),
+                        usage: "cookies set <name> <value>",
+                    })?;
+                    Ok(json!({ "id": id, "action": "cookies_set", "cookies": [{ "name": name, "value": value }] }))
                 }
-                "clear" => Some(json!({ "id": id, "action": "cookies_clear" })),
-                _ => Some(json!({ "id": id, "action": "cookies_get" })),
+                "clear" => Ok(json!({ "id": id, "action": "cookies_clear" })),
+                _ => Ok(json!({ "id": id, "action": "cookies_get" })),
             }
         }
 
         // === Tabs ===
-        "tab" => match rest.get(0).map(|s| *s) {
-            Some("new") => Some(json!({ "id": id, "action": "tab_new", "url": rest.get(1) })),
-            Some("list") => Some(json!({ "id": id, "action": "tab_list" })),
-            Some("close") => {
-                Some(json!({ "id": id, "action": "tab_close", "index": rest.get(1).and_then(|s| s.parse::<i32>().ok()) }))
+        "tab" => {
+            match rest.get(0).map(|s| *s) {
+                Some("new") => Ok(json!({ "id": id, "action": "tab_new", "url": rest.get(1) })),
+                Some("list") => Ok(json!({ "id": id, "action": "tab_list" })),
+                Some("close") => {
+                    Ok(json!({ "id": id, "action": "tab_close", "index": rest.get(1).and_then(|s| s.parse::<i32>().ok()) }))
+                }
+                Some(n) if n.parse::<i32>().is_ok() => {
+                    Ok(json!({ "id": id, "action": "tab_switch", "index": n.parse::<i32>().unwrap() }))
+                }
+                _ => Ok(json!({ "id": id, "action": "tab_list" })),
             }
-            Some(n) if n.parse::<i32>().is_ok() => {
-                Some(json!({ "id": id, "action": "tab_switch", "index": n.parse::<i32>().unwrap() }))
-            }
-            _ => Some(json!({ "id": id, "action": "tab_list" })),
-        },
+        }
 
         // === Window ===
-        "window" => match rest.get(0).map(|s| *s) {
-            Some("new") => Some(json!({ "id": id, "action": "window_new" })),
-            _ => None,
-        },
+        "window" => {
+            const VALID: &[&str] = &["new"];
+            match rest.get(0).map(|s| *s) {
+                Some("new") => Ok(json!({ "id": id, "action": "window_new" })),
+                Some(sub) => Err(ParseError::UnknownSubcommand {
+                    subcommand: sub.to_string(),
+                    valid_options: VALID,
+                }),
+                None => Err(ParseError::MissingArguments {
+                    context: "window".to_string(),
+                    usage: "window <new>",
+                }),
+            }
+        }
 
         // === Frame ===
         "frame" => {
             if rest.get(0).map(|s| *s) == Some("main") {
-                Some(json!({ "id": id, "action": "frame_main" }))
+                Ok(json!({ "id": id, "action": "frame_main" }))
             } else {
-                Some(json!({ "id": id, "action": "frame", "selector": rest.get(0)? }))
+                let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                    context: "frame".to_string(),
+                    usage: "frame <selector|main>",
+                })?;
+                Ok(json!({ "id": id, "action": "frame", "selector": sel }))
             }
         }
 
         // === Dialog ===
-        "dialog" => match rest.get(0).map(|s| *s) {
-            Some("accept") => {
-                Some(json!({ "id": id, "action": "dialog", "response": "accept", "promptText": rest.get(1) }))
+        "dialog" => {
+            const VALID: &[&str] = &["accept", "dismiss"];
+            match rest.get(0).map(|s| *s) {
+                Some("accept") => {
+                    Ok(json!({ "id": id, "action": "dialog", "response": "accept", "promptText": rest.get(1) }))
+                }
+                Some("dismiss") => Ok(json!({ "id": id, "action": "dialog", "response": "dismiss" })),
+                Some(sub) => Err(ParseError::UnknownSubcommand {
+                    subcommand: sub.to_string(),
+                    valid_options: VALID,
+                }),
+                None => Err(ParseError::MissingArguments {
+                    context: "dialog".to_string(),
+                    usage: "dialog <accept|dismiss> [text]",
+                }),
             }
-            Some("dismiss") => Some(json!({ "id": id, "action": "dialog", "response": "dismiss" })),
-            _ => None,
-        },
+        }
 
         // === Debug ===
-        "trace" => match rest.get(0).map(|s| *s) {
-            Some("start") => Some(json!({ "id": id, "action": "trace_start", "path": rest.get(1) })),
-            Some("stop") => Some(json!({ "id": id, "action": "trace_stop", "path": rest.get(1) })),
-            _ => None,
-        },
+        "trace" => {
+            const VALID: &[&str] = &["start", "stop"];
+            match rest.get(0).map(|s| *s) {
+                Some("start") => Ok(json!({ "id": id, "action": "trace_start", "path": rest.get(1) })),
+                Some("stop") => Ok(json!({ "id": id, "action": "trace_stop", "path": rest.get(1) })),
+                Some(sub) => Err(ParseError::UnknownSubcommand {
+                    subcommand: sub.to_string(),
+                    valid_options: VALID,
+                }),
+                None => Err(ParseError::MissingArguments {
+                    context: "trace".to_string(),
+                    usage: "trace <start|stop> [path]",
+                }),
+            }
+        }
         "console" => {
             let clear = rest.iter().any(|&s| s == "--clear");
-            Some(json!({ "id": id, "action": "console", "clear": clear }))
+            Ok(json!({ "id": id, "action": "console", "clear": clear }))
         }
         "errors" => {
             let clear = rest.iter().any(|&s| s == "--clear");
-            Some(json!({ "id": id, "action": "errors", "clear": clear }))
+            Ok(json!({ "id": id, "action": "errors", "clear": clear }))
+        }
+        "highlight" => {
+            let sel = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+                context: "highlight".to_string(),
+                usage: "highlight <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "highlight", "selector": sel }))
         }
-        "highlight" => Some(json!({ "id": id, "action": "highlight", "selector": rest.get(0)? })),
 
         // === State ===
-        "state" => match rest.get(0).map(|s| *s) {
-            Some("save") => Some(json!({ "id": id, "action": "state_save", "path": rest.get(1)? })),
-            Some("load") => Some(json!({ "id": id, "action": "state_load", "path": rest.get(1)? })),
-            _ => None,
-        },
+        "state" => {
+            const VALID: &[&str] = &["save", "load"];
+            match rest.get(0).map(|s| *s) {
+                Some("save") => {
+                    let path = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                        context: "state save".to_string(),
+                        usage: "state save <path>",
+                    })?;
+                    Ok(json!({ "id": id, "action": "state_save", "path": path }))
+                }
+                Some("load") => {
+                    let path = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                        context: "state load".to_string(),
+                        usage: "state load <path>",
+                    })?;
+                    Ok(json!({ "id": id, "action": "state_load", "path": path }))
+                }
+                Some(sub) => Err(ParseError::UnknownSubcommand {
+                    subcommand: sub.to_string(),
+                    valid_options: VALID,
+                }),
+                None => Err(ParseError::MissingArguments {
+                    context: "state".to_string(),
+                    usage: "state <save|load> <path>",
+                }),
+            }
+        }
 
-        _ => None,
+        _ => Err(ParseError::UnknownCommand {
+            command: cmd.to_string(),
+        }),
     }
 }
 
-fn parse_find(rest: &[&str], id: &str) -> Option<Value> {
-    let locator = rest.get(0)?;
-    let value = rest.get(1)?;
-    let subaction = rest.get(2).unwrap_or(&"click");
-    let fill_value = if rest.len() > 3 {
-        Some(rest[3..].join(" "))
-    } else {
-        None
-    };
+fn parse_get(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["text", "html", "value", "attr", "url", "title", "count", "box"];
+    
+    match rest.get(0).map(|s| *s) {
+        Some("text") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "get text".to_string(),
+                usage: "get text <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "gettext", "selector": sel }))
+        }
+        Some("html") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "get html".to_string(),
+                usage: "get html <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "innerhtml", "selector": sel }))
+        }
+        Some("value") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "get value".to_string(),
+                usage: "get value <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "inputvalue", "selector": sel }))
+        }
+        Some("attr") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "get attr".to_string(),
+                usage: "get attr <selector> <attribute>",
+            })?;
+            let attr = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                context: "get attr".to_string(),
+                usage: "get attr <selector> <attribute>",
+            })?;
+            Ok(json!({ "id": id, "action": "getattribute", "selector": sel, "attribute": attr }))
+        }
+        Some("url") => Ok(json!({ "id": id, "action": "url" })),
+        Some("title") => Ok(json!({ "id": id, "action": "title" })),
+        Some("count") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "get count".to_string(),
+                usage: "get count <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "count", "selector": sel }))
+        }
+        Some("box") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "get box".to_string(),
+                usage: "get box <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "boundingbox", "selector": sel }))
+        }
+        Some(sub) => Err(ParseError::UnknownSubcommand {
+            subcommand: sub.to_string(),
+            valid_options: VALID,
+        }),
+        None => Err(ParseError::MissingArguments {
+            context: "get".to_string(),
+            usage: "get <text|html|value|attr|url|title|count|box> [args...]",
+        }),
+    }
+}
 
+fn parse_is(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["visible", "enabled", "checked"];
+    
+    match rest.get(0).map(|s| *s) {
+        Some("visible") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "is visible".to_string(),
+                usage: "is visible <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "isvisible", "selector": sel }))
+        }
+        Some("enabled") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "is enabled".to_string(),
+                usage: "is enabled <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "isenabled", "selector": sel }))
+        }
+        Some("checked") => {
+            let sel = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "is checked".to_string(),
+                usage: "is checked <selector>",
+            })?;
+            Ok(json!({ "id": id, "action": "ischecked", "selector": sel }))
+        }
+        Some(sub) => Err(ParseError::UnknownSubcommand {
+            subcommand: sub.to_string(),
+            valid_options: VALID,
+        }),
+        None => Err(ParseError::MissingArguments {
+            context: "is".to_string(),
+            usage: "is <visible|enabled|checked> <selector>",
+        }),
+    }
+}
+
+fn parse_find(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["role", "text", "label", "placeholder", "alt", "title", "testid", "first", "last", "nth"];
+    
+    let locator = rest.get(0).ok_or_else(|| ParseError::MissingArguments {
+        context: "find".to_string(),
+        usage: "find <locator> <value> [action] [text]",
+    })?;
+    
     let name_idx = rest.iter().position(|&s| s == "--name");
     let name = name_idx.and_then(|i| rest.get(i + 1).map(|s| *s));
     let exact = rest.iter().any(|&s| s == "--exact");
 
     match *locator {
-        "role" => Some(json!({ "id": id, "action": "getbyrole", "role": value, "subaction": subaction, "value": fill_value, "name": name, "exact": exact })),
-        "text" => Some(json!({ "id": id, "action": "getbytext", "text": value, "subaction": subaction, "exact": exact })),
-        "label" => Some(json!({ "id": id, "action": "getbylabel", "label": value, "subaction": subaction, "value": fill_value, "exact": exact })),
-        "placeholder" => Some(json!({ "id": id, "action": "getbyplaceholder", "placeholder": value, "subaction": subaction, "value": fill_value, "exact": exact })),
-        "alt" => Some(json!({ "id": id, "action": "getbyalttext", "text": value, "subaction": subaction, "exact": exact })),
-        "title" => Some(json!({ "id": id, "action": "getbytitle", "text": value, "subaction": subaction, "exact": exact })),
-        "testid" => Some(json!({ "id": id, "action": "getbytestid", "testId": value, "subaction": subaction, "value": fill_value })),
-        "first" => Some(json!({ "id": id, "action": "nth", "selector": value, "index": 0, "subaction": subaction, "value": fill_value })),
-        "last" => Some(json!({ "id": id, "action": "nth", "selector": value, "index": -1, "subaction": subaction, "value": fill_value })),
+        "role" | "text" | "label" | "placeholder" | "alt" | "title" | "testid" | "first" | "last" => {
+            let value = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: format!("find {}", locator),
+                usage: match *locator {
+                    "role" => "find role <role> [action] [--name <name>] [--exact]",
+                    "text" => "find text <text> [action] [--exact]",
+                    "label" => "find label <label> [action] [text] [--exact]",
+                    "placeholder" => "find placeholder <text> [action] [text] [--exact]",
+                    "alt" => "find alt <text> [action] [--exact]",
+                    "title" => "find title <text> [action] [--exact]",
+                    "testid" => "find testid <id> [action] [text]",
+                    "first" => "find first <selector> [action] [text]",
+                    "last" => "find last <selector> [action] [text]",
+                    _ => "find <locator> <value> [action] [text]",
+                },
+            })?;
+            let subaction = rest.get(2).unwrap_or(&"click");
+            let fill_value = if rest.len() > 3 {
+                Some(rest[3..].join(" "))
+            } else {
+                None
+            };
+
+            match *locator {
+                "role" => Ok(json!({ "id": id, "action": "getbyrole", "role": value, "subaction": subaction, "value": fill_value, "name": name, "exact": exact })),
+                "text" => Ok(json!({ "id": id, "action": "getbytext", "text": value, "subaction": subaction, "exact": exact })),
+                "label" => Ok(json!({ "id": id, "action": "getbylabel", "label": value, "subaction": subaction, "value": fill_value, "exact": exact })),
+                "placeholder" => Ok(json!({ "id": id, "action": "getbyplaceholder", "placeholder": value, "subaction": subaction, "value": fill_value, "exact": exact })),
+                "alt" => Ok(json!({ "id": id, "action": "getbyalttext", "text": value, "subaction": subaction, "exact": exact })),
+                "title" => Ok(json!({ "id": id, "action": "getbytitle", "text": value, "subaction": subaction, "exact": exact })),
+                "testid" => Ok(json!({ "id": id, "action": "getbytestid", "testId": value, "subaction": subaction, "value": fill_value })),
+                "first" => Ok(json!({ "id": id, "action": "nth", "selector": value, "index": 0, "subaction": subaction, "value": fill_value })),
+                "last" => Ok(json!({ "id": id, "action": "nth", "selector": value, "index": -1, "subaction": subaction, "value": fill_value })),
+                _ => unreachable!(),
+            }
+        }
         "nth" => {
-            let idx = value.parse::<i32>().ok()?;
-            let sel = rest.get(2)?;
+            let idx_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "find nth".to_string(),
+                usage: "find nth <index> <selector> [action] [text]",
+            })?;
+            let idx = idx_str.parse::<i32>().map_err(|_| ParseError::MissingArguments {
+                context: "find nth".to_string(),
+                usage: "find nth <index> <selector> [action] [text]",
+            })?;
+            let sel = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                context: "find nth".to_string(),
+                usage: "find nth <index> <selector> [action] [text]",
+            })?;
             let sub = rest.get(3).unwrap_or(&"click");
             let fv = if rest.len() > 4 {
                 Some(rest[4..].join(" "))
             } else {
                 None
             };
-            Some(json!({ "id": id, "action": "nth", "selector": sel, "index": idx, "subaction": sub, "value": fv }))
+            Ok(json!({ "id": id, "action": "nth", "selector": sel, "index": idx, "subaction": sub, "value": fv }))
         }
-        _ => None,
+        _ => Err(ParseError::UnknownSubcommand {
+            subcommand: locator.to_string(),
+            valid_options: VALID,
+        }),
     }
 }
 
-fn parse_set(rest: &[&str], id: &str) -> Option<Value> {
+fn parse_mouse(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["move", "down", "up", "wheel"];
+    
+    match rest.get(0).map(|s| *s) {
+        Some("move") => {
+            let x_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "mouse move".to_string(),
+                usage: "mouse move <x> <y>",
+            })?;
+            let y_str = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                context: "mouse move".to_string(),
+                usage: "mouse move <x> <y>",
+            })?;
+            let x = x_str.parse::<i32>().map_err(|_| ParseError::MissingArguments {
+                context: "mouse move".to_string(),
+                usage: "mouse move <x> <y>",
+            })?;
+            let y = y_str.parse::<i32>().map_err(|_| ParseError::MissingArguments {
+                context: "mouse move".to_string(),
+                usage: "mouse move <x> <y>",
+            })?;
+            Ok(json!({ "id": id, "action": "mousemove", "x": x, "y": y }))
+        }
+        Some("down") => {
+            Ok(json!({ "id": id, "action": "mousedown", "button": rest.get(1).unwrap_or(&"left") }))
+        }
+        Some("up") => {
+            Ok(json!({ "id": id, "action": "mouseup", "button": rest.get(1).unwrap_or(&"left") }))
+        }
+        Some("wheel") => {
+            let dy = rest.get(1).and_then(|s| s.parse::<i32>().ok()).unwrap_or(100);
+            let dx = rest.get(2).and_then(|s| s.parse::<i32>().ok()).unwrap_or(0);
+            Ok(json!({ "id": id, "action": "mousewheel", "deltaX": dx, "deltaY": dy }))
+        }
+        Some(sub) => Err(ParseError::UnknownSubcommand {
+            subcommand: sub.to_string(),
+            valid_options: VALID,
+        }),
+        None => Err(ParseError::MissingArguments {
+            context: "mouse".to_string(),
+            usage: "mouse <move|down|up|wheel> [args...]",
+        }),
+    }
+}
+
+fn parse_set(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["viewport", "device", "geo", "geolocation", "offline", "headers", "credentials", "auth", "media"];
+    
     match rest.get(0).map(|s| *s) {
         Some("viewport") => {
-            let w = rest.get(1)?.parse::<i32>().ok()?;
-            let h = rest.get(2)?.parse::<i32>().ok()?;
-            Some(json!({ "id": id, "action": "viewport", "width": w, "height": h }))
+            let w_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "set viewport".to_string(),
+                usage: "set viewport <width> <height>",
+            })?;
+            let h_str = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                context: "set viewport".to_string(),
+                usage: "set viewport <width> <height>",
+            })?;
+            let w = w_str.parse::<i32>().map_err(|_| ParseError::MissingArguments {
+                context: "set viewport".to_string(),
+                usage: "set viewport <width> <height>",
+            })?;
+            let h = h_str.parse::<i32>().map_err(|_| ParseError::MissingArguments {
+                context: "set viewport".to_string(),
+                usage: "set viewport <width> <height>",
+            })?;
+            Ok(json!({ "id": id, "action": "viewport", "width": w, "height": h }))
+        }
+        Some("device") => {
+            let dev = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "set device".to_string(),
+                usage: "set device <name>",
+            })?;
+            Ok(json!({ "id": id, "action": "device", "device": dev }))
         }
-        Some("device") => Some(json!({ "id": id, "action": "device", "device": rest.get(1)? })),
         Some("geo") | Some("geolocation") => {
-            let lat = rest.get(1)?.parse::<f64>().ok()?;
-            let lng = rest.get(2)?.parse::<f64>().ok()?;
-            Some(json!({ "id": id, "action": "geolocation", "latitude": lat, "longitude": lng }))
+            let lat_str = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "set geo".to_string(),
+                usage: "set geo <latitude> <longitude>",
+            })?;
+            let lng_str = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                context: "set geo".to_string(),
+                usage: "set geo <latitude> <longitude>",
+            })?;
+            let lat = lat_str.parse::<f64>().map_err(|_| ParseError::MissingArguments {
+                context: "set geo".to_string(),
+                usage: "set geo <latitude> <longitude>",
+            })?;
+            let lng = lng_str.parse::<f64>().map_err(|_| ParseError::MissingArguments {
+                context: "set geo".to_string(),
+                usage: "set geo <latitude> <longitude>",
+            })?;
+            Ok(json!({ "id": id, "action": "geolocation", "latitude": lat, "longitude": lng }))
         }
         Some("offline") => {
             let off = rest.get(1).map(|s| *s != "off" && *s != "false").unwrap_or(true);
-            Some(json!({ "id": id, "action": "offline", "offline": off }))
+            Ok(json!({ "id": id, "action": "offline", "offline": off }))
         }
         Some("headers") => {
-            let headers_json = rest.get(1)?;
-            Some(json!({ "id": id, "action": "headers", "headers": headers_json }))
+            let headers_json = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "set headers".to_string(),
+                usage: "set headers <json>",
+            })?;
+            Ok(json!({ "id": id, "action": "headers", "headers": headers_json }))
         }
         Some("credentials") | Some("auth") => {
-            Some(json!({ "id": id, "action": "credentials", "username": rest.get(1)?, "password": rest.get(2)? }))
+            let user = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "set credentials".to_string(),
+                usage: "set credentials <username> <password>",
+            })?;
+            let pass = rest.get(2).ok_or_else(|| ParseError::MissingArguments {
+                context: "set credentials".to_string(),
+                usage: "set credentials <username> <password>",
+            })?;
+            Ok(json!({ "id": id, "action": "credentials", "username": user, "password": pass }))
         }
         Some("media") => {
             let color = if rest.iter().any(|&s| s == "dark") {
@@ -363,9 +750,90 @@ fn parse_set(rest: &[&str], id: &str) -> Option<Value> {
                 "no-preference"
             };
             let reduced = rest.iter().any(|&s| s == "reduced-motion");
-            Some(json!({ "id": id, "action": "media", "colorScheme": color, "reducedMotion": reduced }))
+            Ok(json!({ "id": id, "action": "media", "colorScheme": color, "reducedMotion": reduced }))
         }
-        _ => None,
+        Some(sub) => Err(ParseError::UnknownSubcommand {
+            subcommand: sub.to_string(),
+            valid_options: VALID,
+        }),
+        None => Err(ParseError::MissingArguments {
+            context: "set".to_string(),
+            usage: "set <viewport|device|geo|offline|headers|credentials|media> [args...]",
+        }),
+    }
+}
+
+fn parse_network(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["route", "unroute", "requests"];
+    
+    match rest.get(0).map(|s| *s) {
+        Some("route") => {
+            let url = rest.get(1).ok_or_else(|| ParseError::MissingArguments {
+                context: "network route".to_string(),
+                usage: "network route <url> [--abort|--body <json>]",
+            })?;
+            let abort = rest.iter().any(|&s| s == "--abort");
+            let body_idx = rest.iter().position(|&s| s == "--body");
+            let body = body_idx.and_then(|i| rest.get(i + 1).map(|s| *s));
+            Ok(json!({ "id": id, "action": "route", "url": url, "abort": abort, "body": body }))
+        }
+        Some("unroute") => Ok(json!({ "id": id, "action": "unroute", "url": rest.get(1) })),
+        Some("requests") => {
+            let clear = rest.iter().any(|&s| s == "--clear");
+            let filter_idx = rest.iter().position(|&s| s == "--filter");
+            let filter = filter_idx.and_then(|i| rest.get(i + 1).map(|s| *s));
+            Ok(json!({ "id": id, "action": "requests", "clear": clear, "filter": filter }))
+        }
+        Some(sub) => Err(ParseError::UnknownSubcommand {
+            subcommand: sub.to_string(),
+            valid_options: VALID,
+        }),
+        None => Err(ParseError::MissingArguments {
+            context: "network".to_string(),
+            usage: "network <route|unroute|requests> [args...]",
+        }),
+    }
+}
+
+fn parse_storage(rest: &[&str], id: &str) -> Result<Value, ParseError> {
+    const VALID: &[&str] = &["local", "session"];
+    
+    match rest.get(0).map(|s| *s) {
+        Some("local") | Some("session") => {
+            let storage_type = rest.get(0).unwrap();
+            let op = rest.get(1).unwrap_or(&"get");
+            let key = rest.get(2);
+            let value = rest.get(3);
+            match *op {
+                "set" => {
+                    let k = key.ok_or_else(|| ParseError::MissingArguments {
+                        context: format!("storage {} set", storage_type),
+                        usage: "storage <local|session> set <key> <value>",
+                    })?;
+                    let v = value.ok_or_else(|| ParseError::MissingArguments {
+                        context: format!("storage {} set", storage_type),
+                        usage: "storage <local|session> set <key> <value>",
+                    })?;
+                    Ok(json!({ "id": id, "action": "storage_set", "type": storage_type, "key": k, "value": v }))
+                }
+                "clear" => Ok(json!({ "id": id, "action": "storage_clear", "type": storage_type })),
+                _ => {
+                    let mut cmd = json!({ "id": id, "action": "storage_get", "type": storage_type });
+                    if let Some(k) = key {
+                        cmd.as_object_mut().unwrap().insert("key".to_string(), json!(k));
+                    }
+                    Ok(cmd)
+                }
+            }
+        }
+        Some(sub) => Err(ParseError::UnknownSubcommand {
+            subcommand: sub.to_string(),
+            valid_options: VALID,
+        }),
+        None => Err(ParseError::MissingArguments {
+            context: "storage".to_string(),
+            usage: "storage <local|session> [get|set|clear] [key] [value]",
+        }),
     }
 }
 
@@ -412,7 +880,7 @@ mod tests {
     #[test]
     fn test_cookies_set_missing_value() {
         let result = parse_command(&args("cookies set mycookie"), &default_flags());
-        assert!(result.is_none());
+        assert!(result.is_err());
     }
 
     #[test]
@@ -467,7 +935,7 @@ mod tests {
     #[test]
     fn test_storage_set_missing_value() {
         let result = parse_command(&args("storage local set mykey"), &default_flags());
-        assert!(result.is_none());
+        assert!(result.is_err());
     }
 
     #[test]
@@ -487,7 +955,7 @@ mod tests {
     #[test]
     fn test_storage_invalid_type() {
         let result = parse_command(&args("storage invalid"), &default_flags());
-        assert!(result.is_none());
+        assert!(result.is_err());
     }
 
     // === Navigation Tests ===
@@ -627,12 +1095,44 @@ mod tests {
     #[test]
     fn test_unknown_command() {
         let result = parse_command(&args("unknowncommand"), &default_flags());
-        assert!(result.is_none());
+        assert!(result.is_err());
+        assert!(matches!(result.unwrap_err(), ParseError::UnknownCommand { .. }));
     }
 
     #[test]
     fn test_empty_args() {
         let result = parse_command(&[], &default_flags());
-        assert!(result.is_none());
+        assert!(result.is_err());
+        assert!(matches!(result.unwrap_err(), ParseError::MissingArguments { .. }));
+    }
+
+    // === Error message tests ===
+
+    #[test]
+    fn test_get_missing_subcommand() {
+        let result = parse_command(&args("get"), &default_flags());
+        assert!(result.is_err());
+        let err = result.unwrap_err();
+        assert!(matches!(err, ParseError::MissingArguments { .. }));
+        assert!(err.format().contains("get"));
+    }
+
+    #[test]
+    fn test_get_unknown_subcommand() {
+        let result = parse_command(&args("get foo"), &default_flags());
+        assert!(result.is_err());
+        let err = result.unwrap_err();
+        assert!(matches!(err, ParseError::UnknownSubcommand { .. }));
+        assert!(err.format().contains("foo"));
+        assert!(err.format().contains("text"));
+    }
+
+    #[test]
+    fn test_get_text_missing_selector() {
+        let result = parse_command(&args("get text"), &default_flags());
+        assert!(result.is_err());
+        let err = result.unwrap_err();
+        assert!(matches!(err, ParseError::MissingArguments { .. }));
+        assert!(err.format().contains("get text"));
     }
 }
diff --git a/cli/src/main.rs b/cli/src/main.rs
index d715e3f..cb0f767 100644
--- a/cli/src/main.rs
+++ b/cli/src/main.rs
@@ -8,7 +8,7 @@ use serde_json::json;
 use std::env;
 use std::process::exit;
 
-use commands::{gen_id, parse_command};
+use commands::{gen_id, parse_command, ParseError};
 use connection::{ensure_daemon, send_command};
 use flags::{clean_args, parse_flags};
 use install::run_install;
@@ -32,13 +32,22 @@ fn main() {
     }
 
     let cmd = match parse_command(&clean, &flags) {
-        Some(c) => c,
-        None => {
-            eprintln!(
-                "\x1b[31mUnknown command:\x1b[0m {}",
-                clean.get(0).unwrap_or(&String::new())
-            );
-            eprintln!("\x1b[2mRun: agent-browser --help\x1b[0m");
+        Ok(c) => c,
+        Err(e) => {
+            if flags.json {
+                let error_type = match &e {
+                    ParseError::UnknownCommand { .. } => "unknown_command",
+                    ParseError::UnknownSubcommand { .. } => "unknown_subcommand",
+                    ParseError::MissingArguments { .. } => "missing_arguments",
+                };
+                println!(
+                    r#"{{"success":false,"error":"{}","type":"{}"}}"#,
+                    e.format().replace('\n', " "),
+                    error_type
+                );
+            } else {
+                eprintln!("\x1b[31m{}\x1b[0m", e.format());
+            }
             exit(1);
         }
     };