leeguooooo
c99838a034
Passing a Cloudflare challenge mints an HttpOnly cf_clearance cookie bound to IP+UA. 'chrome-use cf-status' (aliases cf/cloudflare-status/clearance) reports whether the active page is currently a CF challenge and whether a still-valid cf_clearance exists (read via CDP — HttpOnly is invisible to document.cookie), plus CF_VERIFIED_DEVICE trust, and a recommendation: proceed (already cleared, don't re-solve) / solve (challenge up, no clearance) / reissue (clearance present but page still blocks → IP/UA drifted). Lets an agent avoid re-solving what it already cleared — the persistence optimization. Pure helpers unit-tested; live -verified on a real cf_clearance.
3680 lines
130 KiB
Rust
3680 lines
130 KiB
Rust
use std::sync::OnceLock;
|
|
|
|
use crate::color;
|
|
use crate::connection::Response;
|
|
|
|
static BOUNDARY_NONCE: OnceLock<String> = OnceLock::new();
|
|
|
|
/// Per-process nonce for content boundary markers. Uses a CSPRNG (getrandom) so
|
|
/// that untrusted page content cannot predict or spoof the boundary delimiter.
|
|
/// Process ID or timestamps would be insufficient since pages can read those.
|
|
fn get_boundary_nonce() -> &'static str {
|
|
BOUNDARY_NONCE.get_or_init(|| {
|
|
let mut buf = [0u8; 16];
|
|
getrandom::getrandom(&mut buf).expect("failed to generate random nonce");
|
|
buf.iter().map(|b| format!("{:02x}", b)).collect()
|
|
})
|
|
}
|
|
|
|
#[derive(Default)]
|
|
pub struct OutputOptions {
|
|
pub json: bool,
|
|
pub content_boundaries: bool,
|
|
pub max_output: Option<usize>,
|
|
}
|
|
|
|
impl OutputOptions {
|
|
pub fn from_flags(flags: &crate::flags::Flags) -> Self {
|
|
Self {
|
|
json: flags.json,
|
|
content_boundaries: flags.content_boundaries,
|
|
max_output: flags.max_output,
|
|
}
|
|
}
|
|
}
|
|
|
|
fn truncate_if_needed(content: &str, max: Option<usize>) -> String {
|
|
let Some(limit) = max else {
|
|
return content.to_string();
|
|
};
|
|
// Fast path: byte length is a lower bound on char count, so if the
|
|
// byte length is within the limit the char count must be too.
|
|
if content.len() <= limit {
|
|
return content.to_string();
|
|
}
|
|
// Find the byte offset of the limit-th character.
|
|
match content.char_indices().nth(limit).map(|(i, _)| i) {
|
|
Some(byte_offset) => {
|
|
let total_chars = content.chars().count();
|
|
format!(
|
|
"{}\n[truncated: showing {} of {} chars. Use --max-output to adjust]",
|
|
&content[..byte_offset],
|
|
limit,
|
|
total_chars
|
|
)
|
|
}
|
|
// Content has fewer than `limit` chars despite more bytes
|
|
None => content.to_string(),
|
|
}
|
|
}
|
|
|
|
fn print_with_boundaries(content: &str, origin: Option<&str>, opts: &OutputOptions) {
|
|
let content = truncate_if_needed(content, opts.max_output);
|
|
if opts.content_boundaries {
|
|
let origin_str = origin.unwrap_or("unknown");
|
|
let nonce = get_boundary_nonce();
|
|
println!(
|
|
"--- AGENT_BROWSER_PAGE_CONTENT nonce={} origin={} ---",
|
|
nonce, origin_str
|
|
);
|
|
println!("{}", content);
|
|
println!("--- END_AGENT_BROWSER_PAGE_CONTENT nonce={} ---", nonce);
|
|
} else {
|
|
println!("{}", content);
|
|
}
|
|
}
|
|
|
|
fn format_storage_value(value: &serde_json::Value) -> String {
|
|
value
|
|
.as_str()
|
|
.map(ToString::to_string)
|
|
.unwrap_or_else(|| serde_json::to_string(value).unwrap_or_default())
|
|
}
|
|
|
|
fn format_storage_text(data: &serde_json::Value) -> Option<String> {
|
|
if let Some(entries) = data.get("data").and_then(|v| v.as_object()) {
|
|
if entries.is_empty() {
|
|
return Some("No storage entries".to_string());
|
|
}
|
|
|
|
let lines = entries
|
|
.iter()
|
|
.map(|(key, value)| format!("{}: {}", key, format_storage_value(value)))
|
|
.collect::<Vec<_>>();
|
|
return Some(lines.join("\n"));
|
|
}
|
|
|
|
let key = data.get("key").and_then(|v| v.as_str())?;
|
|
let value = data.get("value")?;
|
|
Some(format!("{}: {}", key, format_storage_value(value)))
|
|
}
|
|
|
|
fn format_stream_status_text(action: Option<&str>, data: &serde_json::Value) -> Option<String> {
|
|
match action {
|
|
Some("stream_disable") => data
|
|
.get("disabled")
|
|
.and_then(|v| v.as_bool())
|
|
.filter(|disabled| *disabled)
|
|
.map(|_| "Streaming disabled".to_string()),
|
|
Some("stream_enable") | Some("stream_status") => {
|
|
let enabled = data.get("enabled").and_then(|v| v.as_bool())?;
|
|
if !enabled {
|
|
return Some("Streaming disabled".to_string());
|
|
}
|
|
|
|
let port = data.get("port").and_then(|v| v.as_u64())?;
|
|
let connected = data
|
|
.get("connected")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
let screencasting = data
|
|
.get("screencasting")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
|
|
Some(format!(
|
|
"Streaming enabled on ws://127.0.0.1:{port}\nConnected: {connected}\nScreencasting: {screencasting}"
|
|
))
|
|
}
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
/// Shorten an over-long string by keeping its head and tail and eliding the
|
|
/// middle, with a char count. Used so multi-KB URLs (JWT/OTP login links) don't
|
|
/// flood `tab list`.
|
|
fn truncate_middle(s: &str, max: usize) -> String {
|
|
let n = s.chars().count();
|
|
if n <= max {
|
|
return s.to_string();
|
|
}
|
|
let keep = max.saturating_sub(1) / 2;
|
|
let head: String = s.chars().take(keep).collect();
|
|
let tail: String = s.chars().skip(n - keep).collect();
|
|
format!("{head}…{tail} [{n} chars]")
|
|
}
|
|
|
|
pub fn print_response_with_opts(resp: &Response, action: Option<&str>, opts: &OutputOptions) {
|
|
if opts.json {
|
|
if opts.content_boundaries {
|
|
let mut json_val = serde_json::to_value(resp).unwrap_or_default();
|
|
if let Some(obj) = json_val.as_object_mut() {
|
|
let nonce = get_boundary_nonce();
|
|
let origin = obj
|
|
.get("data")
|
|
.and_then(|d| d.get("origin"))
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("unknown");
|
|
obj.insert(
|
|
"_boundary".to_string(),
|
|
serde_json::json!({
|
|
"nonce": nonce,
|
|
"origin": origin,
|
|
}),
|
|
);
|
|
}
|
|
println!("{}", serde_json::to_string(&json_val).unwrap_or_default());
|
|
} else {
|
|
println!("{}", serde_json::to_string(resp).unwrap_or_default());
|
|
}
|
|
// JSON mode includes the warning field in the JSON payload already
|
|
return;
|
|
}
|
|
|
|
if !resp.success {
|
|
eprintln!(
|
|
"{} {}",
|
|
color::error_indicator(),
|
|
resp.error.as_deref().unwrap_or("Unknown error")
|
|
);
|
|
// Still print dialog warning after errors, since a pending dialog
|
|
// is the most common cause of commands timing out
|
|
if let Some(ref warning) = resp.warning {
|
|
eprintln!("{} {}", color::warning_indicator(), warning);
|
|
}
|
|
return;
|
|
}
|
|
|
|
if let Some(data) = &resp.data {
|
|
// A click that opened a new tab: surface it so the agent doesn't read the
|
|
// unchanged old page as a failed click (issue #24-A).
|
|
if let Some(opened) = data.get("openedTab") {
|
|
let tid = opened.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
|
|
let url = opened.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
let followed = data
|
|
.get("followed")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
let verb = if followed {
|
|
"switched to new tab"
|
|
} else {
|
|
"opened new tab"
|
|
};
|
|
eprintln!(
|
|
"{} {} [{}] {}",
|
|
color::cyan("→"),
|
|
verb,
|
|
tid,
|
|
color::dim(url)
|
|
);
|
|
}
|
|
|
|
// `current`: the active tab's stable handle (#26).
|
|
if data
|
|
.get("current")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
{
|
|
let tid = data.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
|
|
let title = data.get("title").and_then(|v| v.as_str()).unwrap_or("");
|
|
let url = data.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
let target = data.get("targetId").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!("{} [{}] {} - {}", color::cyan("→"), tid, title, url);
|
|
println!(" {}", color::dim(&format!("target: {}", target)));
|
|
return;
|
|
}
|
|
|
|
// Cloudflare challenge/clearance preflight (`cf-status`). Checked early
|
|
// because its response carries `url`/`title`, which later generic
|
|
// renderers would otherwise swallow.
|
|
if action == Some("cf_status") {
|
|
let challenged = data.get("challenged").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let rec = data.get("recommendation").and_then(|v| v.as_str()).unwrap_or("?");
|
|
let cl = data.get("clearance");
|
|
let present = cl.and_then(|c| c.get("present")).and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let expired = cl.and_then(|c| c.get("expired")).and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let expires_in = cl.and_then(|c| c.get("expiresIn")).and_then(|v| v.as_i64());
|
|
let device = data.get("deviceVerified").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
|
|
let (icon, headline) = match rec {
|
|
"proceed" => (color::success_indicator().to_string(), "cleared — no challenge, proceed"),
|
|
"solve" => (color::warning_indicator().to_string(), "Cloudflare challenge active, no valid clearance — solve it"),
|
|
"reissue" => (color::warning_indicator().to_string(), "challenge active but a clearance cookie exists — stale (IP/UA changed?), re-solve"),
|
|
_ => (color::cyan("•").to_string(), "unknown"),
|
|
};
|
|
println!("{} {}", icon, headline);
|
|
println!(" challenged: {}", if challenged { "yes" } else { "no" });
|
|
let cl_desc = if !present {
|
|
"absent".to_string()
|
|
} else if expired {
|
|
"present but EXPIRED".to_string()
|
|
} else if let Some(s) = expires_in {
|
|
format!("valid, expires in {}m {}s", s / 60, s % 60)
|
|
} else {
|
|
"present (session)".to_string()
|
|
};
|
|
println!(" cf_clearance: {}", cl_desc);
|
|
println!(" device trusted: {}", if device { "yes (CF_VERIFIED_DEVICE)" } else { "no" });
|
|
return;
|
|
}
|
|
|
|
// Dialog status response
|
|
if action == Some("dialog") {
|
|
if let Some(has_dialog) = data.get("hasDialog").and_then(|v| v.as_bool()) {
|
|
if has_dialog {
|
|
let dtype = data
|
|
.get("type")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("unknown");
|
|
let message = data.get("message").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(
|
|
"{} JavaScript {} dialog is open: \"{}\"",
|
|
color::warning_indicator(),
|
|
dtype,
|
|
message
|
|
);
|
|
if let Some(default_prompt) = data.get("defaultPrompt").and_then(|v| v.as_str())
|
|
{
|
|
println!(" Default prompt text: \"{}\"", default_prompt);
|
|
}
|
|
println!(" Use `dialog accept [text]` or `dialog dismiss` to resolve it");
|
|
} else {
|
|
println!("{} No dialog is currently open", color::success_indicator());
|
|
}
|
|
print_warning(resp);
|
|
return;
|
|
}
|
|
}
|
|
if let Some(output) = format_stream_status_text(action, data) {
|
|
println!("{}", output);
|
|
return;
|
|
}
|
|
if action == Some("storage_get") {
|
|
if let Some(output) = format_storage_text(data) {
|
|
println!("{}", output);
|
|
return;
|
|
}
|
|
}
|
|
// Inspect response (check before generic URL handler since it also has a "url" field)
|
|
if action == Some("inspect") {
|
|
let opened = data
|
|
.get("opened")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
if opened {
|
|
if let Some(url) = data.get("url").and_then(|v| v.as_str()) {
|
|
println!("{} Opened DevTools: {}", color::success_indicator(), url);
|
|
} else {
|
|
println!("{} Opened DevTools", color::success_indicator());
|
|
}
|
|
} else if let Some(err) = data.get("error").and_then(|v| v.as_str()) {
|
|
eprintln!("Could not open DevTools: {}", err);
|
|
}
|
|
return;
|
|
}
|
|
// Navigation response
|
|
if let Some(url) = data.get("url").and_then(|v| v.as_str()) {
|
|
let title = data
|
|
.get("title")
|
|
.and_then(|v| v.as_str())
|
|
.map(str::trim)
|
|
.filter(|t| !t.is_empty());
|
|
match title {
|
|
Some(t) => {
|
|
println!("{} {}", color::success_indicator(), color::bold(t));
|
|
println!(" {}", color::dim(url));
|
|
}
|
|
// Title-less page: show the URL with the checkmark instead of an
|
|
// empty title line.
|
|
None => println!("{} {}", color::success_indicator(), color::dim(url)),
|
|
}
|
|
// Soft warning carried in the response (e.g. the load event timed out
|
|
// but the DOM was ready — issue #10). Goes to stderr so it doesn't
|
|
// pollute the stdout url/title that scripts parse.
|
|
if let Some(w) = data.get("warning").and_then(|v| v.as_str()) {
|
|
eprintln!("⚠ navigation: {w}");
|
|
}
|
|
return;
|
|
}
|
|
if let Some(cdp_url) = data.get("cdpUrl").and_then(|v| v.as_str()) {
|
|
println!("{}", cdp_url);
|
|
return;
|
|
}
|
|
// Diff responses -- route by action to avoid fragile shape probing
|
|
if let Some(obj) = data.as_object() {
|
|
match action {
|
|
Some("diff_snapshot") => {
|
|
print_snapshot_diff(obj);
|
|
return;
|
|
}
|
|
Some("diff_screenshot") => {
|
|
print_screenshot_diff(obj);
|
|
return;
|
|
}
|
|
Some("diff_url") => {
|
|
if let Some(snap_data) = obj.get("snapshot").and_then(|v| v.as_object()) {
|
|
println!("{}", color::bold("Snapshot diff:"));
|
|
print_snapshot_diff(snap_data);
|
|
}
|
|
if let Some(ss_data) = obj.get("screenshot").and_then(|v| v.as_object()) {
|
|
println!("\n{}", color::bold("Screenshot diff:"));
|
|
print_screenshot_diff(ss_data);
|
|
}
|
|
return;
|
|
}
|
|
_ => {}
|
|
}
|
|
}
|
|
let origin = data.get("origin").and_then(|v| v.as_str());
|
|
// Snapshot
|
|
if let Some(snapshot) = data.get("snapshot").and_then(|v| v.as_str()) {
|
|
print_with_boundaries(snapshot, origin, opts);
|
|
// Canvas-app hint: the tree was near-empty but the page paints to a
|
|
// <canvas>, so refs are a dead end — point at the screenshot path.
|
|
if let Some(note) = data.get("note").and_then(|v| v.as_str()) {
|
|
eprintln!("{}", color::dim(note));
|
|
}
|
|
return;
|
|
}
|
|
// Frame list (`chrome-use frames`)
|
|
if action == Some("frames") {
|
|
if let Some(list) = data.get("frames").and_then(|v| v.as_array()) {
|
|
let count = list.len();
|
|
println!(
|
|
"{}",
|
|
color::bold(&format!("{} frame{}", count, if count == 1 { "" } else { "s" }))
|
|
);
|
|
for f in list {
|
|
let idx = f.get("index").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let kind = f.get("kind").and_then(|v| v.as_str()).unwrap_or("?");
|
|
let url = f.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
let len = f.get("textLen").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
println!(
|
|
" [{}] {:<6} {} chars {}",
|
|
idx,
|
|
kind,
|
|
len,
|
|
color::dim(if url.is_empty() { "(about:blank)" } else { url })
|
|
);
|
|
}
|
|
eprintln!(
|
|
"{}",
|
|
color::dim("read everything with: chrome-use get text --all-frames")
|
|
);
|
|
}
|
|
return;
|
|
}
|
|
// Title
|
|
if let Some(title) = data.get("title").and_then(|v| v.as_str()) {
|
|
println!("{}", title);
|
|
return;
|
|
}
|
|
// Text
|
|
if let Some(text) = data.get("text").and_then(|v| v.as_str()) {
|
|
print_with_boundaries(text, origin, opts);
|
|
return;
|
|
}
|
|
// HTML
|
|
if let Some(html) = data.get("html").and_then(|v| v.as_str()) {
|
|
print_with_boundaries(html, origin, opts);
|
|
return;
|
|
}
|
|
// Value
|
|
if let Some(value) = data.get("value").and_then(|v| v.as_str()) {
|
|
println!("{}", value);
|
|
return;
|
|
}
|
|
// Count
|
|
if let Some(count) = data.get("count").and_then(|v| v.as_i64()) {
|
|
println!("{}", count);
|
|
return;
|
|
}
|
|
// Bounding box (get box)
|
|
if action == Some("boundingbox") {
|
|
if let Some(obj) = data.as_object() {
|
|
let x = obj.get("x").and_then(|v| v.as_f64()).unwrap_or(0.0);
|
|
let y = obj.get("y").and_then(|v| v.as_f64()).unwrap_or(0.0);
|
|
let w = obj.get("width").and_then(|v| v.as_f64()).unwrap_or(0.0);
|
|
let h = obj.get("height").and_then(|v| v.as_f64()).unwrap_or(0.0);
|
|
println!("x: {}", x);
|
|
println!("y: {}", y);
|
|
println!("width: {}", w);
|
|
println!("height: {}", h);
|
|
}
|
|
return;
|
|
}
|
|
// Computed styles (get styles)
|
|
if let Some(styles) = data.get("styles").and_then(|v| v.as_object()) {
|
|
for (key, val) in styles {
|
|
let display = match val.as_str() {
|
|
Some(s) => s.to_string(),
|
|
None => val.to_string(),
|
|
};
|
|
println!("{}: {}", key, display);
|
|
}
|
|
return;
|
|
}
|
|
// Boolean results
|
|
if let Some(visible) = data.get("visible").and_then(|v| v.as_bool()) {
|
|
println!("{}", visible);
|
|
return;
|
|
}
|
|
if let Some(enabled) = data.get("enabled").and_then(|v| v.as_bool()) {
|
|
println!("{}", enabled);
|
|
return;
|
|
}
|
|
// Stealth self-check (`stealth status` / `doctor`)
|
|
if let Some(s) = data.get("stealthStatus") {
|
|
let ok = s.get("ok").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let mode = s.get("mode").and_then(|v| v.as_str()).unwrap_or("?");
|
|
println!(
|
|
"{} stealth: {} · mode: {}",
|
|
if ok {
|
|
color::success_indicator().to_string()
|
|
} else {
|
|
color::cyan("•")
|
|
},
|
|
if ok {
|
|
"all checks pass"
|
|
} else {
|
|
"some checks need attention"
|
|
},
|
|
mode
|
|
);
|
|
if let Some(checks) = s.get("checks").and_then(|v| v.as_array()) {
|
|
for c in checks {
|
|
let pass = c.get("pass").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let name = c.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(" {} {}", if pass { "✓" } else { "✗" }, name);
|
|
}
|
|
}
|
|
if let Some(ovs) = s.get("overrides").and_then(|v| v.as_array()) {
|
|
println!(" applied overrides:");
|
|
for o in ovs.iter().filter_map(|v| v.as_str()) {
|
|
println!(" {}", color::dim(&format!("· {o}")));
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
if let Some(checked) = data.get("checked").and_then(|v| v.as_bool()) {
|
|
println!("{}", checked);
|
|
return;
|
|
}
|
|
// Eval result
|
|
if let Some(result) = data.get("result") {
|
|
// Surface which page the eval actually ran on — to stderr, so it
|
|
// never corrupts the parsed value on stdout. Lets an agent catch tab
|
|
// drift (commands landing on the wrong tab) before trusting a result,
|
|
// e.g. a logged-in `fetch` that hit the wrong origin. (In
|
|
// content-boundaries mode the origin is already in the banner.)
|
|
if !opts.content_boundaries {
|
|
if let Some(o) = origin.filter(|o| !o.is_empty()) {
|
|
eprintln!("eval @ {o}");
|
|
}
|
|
}
|
|
let formatted = serde_json::to_string_pretty(result).unwrap_or_default();
|
|
print_with_boundaries(&formatted, origin, opts);
|
|
return;
|
|
}
|
|
// iOS Devices
|
|
if let Some(devices) = data.get("devices").and_then(|v| v.as_array()) {
|
|
if devices.is_empty() {
|
|
println!("No iOS devices available. Open Xcode to download simulator runtimes.");
|
|
return;
|
|
}
|
|
|
|
// Separate real devices from simulators
|
|
let real_devices: Vec<_> = devices
|
|
.iter()
|
|
.filter(|d| {
|
|
d.get("isRealDevice")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
})
|
|
.collect();
|
|
let simulators: Vec<_> = devices
|
|
.iter()
|
|
.filter(|d| {
|
|
!d.get("isRealDevice")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
})
|
|
.collect();
|
|
|
|
if !real_devices.is_empty() {
|
|
println!("Connected Devices:\n");
|
|
for device in real_devices.iter() {
|
|
let name = device
|
|
.get("name")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("Unknown");
|
|
let runtime = device.get("runtime").and_then(|v| v.as_str()).unwrap_or("");
|
|
let udid = device.get("udid").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(" {} {} ({})", color::green("●"), name, runtime);
|
|
println!(" {}", color::dim(udid));
|
|
}
|
|
println!();
|
|
}
|
|
|
|
if !simulators.is_empty() {
|
|
println!("Simulators:\n");
|
|
for device in simulators.iter() {
|
|
let name = device
|
|
.get("name")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("Unknown");
|
|
let runtime = device.get("runtime").and_then(|v| v.as_str()).unwrap_or("");
|
|
let state = device
|
|
.get("state")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("Unknown");
|
|
let udid = device.get("udid").and_then(|v| v.as_str()).unwrap_or("");
|
|
let state_indicator = if state == "Booted" {
|
|
color::green("●")
|
|
} else {
|
|
color::dim("○")
|
|
};
|
|
println!(" {} {} ({})", state_indicator, name, runtime);
|
|
println!(" {}", color::dim(udid));
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
// Tabs
|
|
if let Some(tabs) = data.get("tabs").and_then(|v| v.as_array()) {
|
|
// `tab list --full` prints untruncated URLs so a long SSO/redirect
|
|
// URL can actually be re-opened after a stale session (issue #19).
|
|
let full = data.get("full").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
for tab in tabs {
|
|
let tab_id = tab.get("tabId").and_then(|v| v.as_str()).unwrap_or("?");
|
|
let tab_label = tab.get("label").and_then(|v| v.as_str());
|
|
let title = tab
|
|
.get("title")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("Untitled");
|
|
// A page can set its title to a multi-KB string (e.g. equal to a
|
|
// giant JWT/OTP URL); truncate it like the URL so the row stays
|
|
// readable.
|
|
let title = truncate_middle(title, 120);
|
|
let title = title.as_str();
|
|
let url = tab.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
// Truncate very long URLs (e.g. multi-KB JWT/OTP login links) so
|
|
// the list stays readable instead of flooding the terminal —
|
|
// unless `--full` was asked for (to re-open the exact URL).
|
|
let url = if full {
|
|
url.to_string()
|
|
} else {
|
|
truncate_middle(url, 120)
|
|
};
|
|
let active = tab.get("active").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let marker = if active {
|
|
color::cyan("→")
|
|
} else {
|
|
" ".to_string()
|
|
};
|
|
if let Some(label) = tab_label {
|
|
println!("{} [{}] {} {} - {}", marker, tab_id, label, title, url);
|
|
} else {
|
|
println!("{} [{}] {} - {}", marker, tab_id, title, url);
|
|
}
|
|
// `--full` also surfaces the stable cross-session CDP targetId so
|
|
// a stranded tab can be adopted from another session via
|
|
// `tab <targetId>` (issue #21).
|
|
if full {
|
|
if let Some(target_id) = tab.get("targetId").and_then(|v| v.as_str()) {
|
|
println!(" {}", color::dim(&format!("target: {}", target_id)));
|
|
}
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
// Tab switch
|
|
if action == Some("tab_switch") {
|
|
if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_str()) {
|
|
let warning = data.get("warning").and_then(|v| v.as_str());
|
|
// A non-responding session isn't a real success — show a warning
|
|
// indicator instead of the green ✓ (issue #29.3).
|
|
let indicator = if warning.is_some() {
|
|
color::warning_indicator()
|
|
} else {
|
|
color::success_indicator()
|
|
};
|
|
if let Some(url) = data.get("url").and_then(|v| v.as_str()) {
|
|
println!("{} Switched to tab [{}] ({})", indicator, tab_id, url);
|
|
} else {
|
|
println!("{} Switched to tab [{}]", indicator, tab_id);
|
|
}
|
|
if let Some(w) = warning {
|
|
eprintln!("{}", color::dim(w));
|
|
}
|
|
return;
|
|
}
|
|
}
|
|
// New tab/window
|
|
if let Some(tab_id) = data.get("tabId").and_then(|v| v.as_str()) {
|
|
if let Some(total) = data.get("total").and_then(|v| v.as_i64()) {
|
|
let label_noun = match action {
|
|
Some("window_new") => "Window opened",
|
|
_ => "Tab opened",
|
|
};
|
|
let tab_label = data.get("label").and_then(|v| v.as_str());
|
|
if let Some(lbl) = tab_label {
|
|
println!(
|
|
"{} {} [{}] {} ({} total)",
|
|
color::success_indicator(),
|
|
label_noun,
|
|
tab_id,
|
|
lbl,
|
|
total
|
|
);
|
|
} else {
|
|
println!(
|
|
"{} {} [{}] ({} total)",
|
|
color::success_indicator(),
|
|
label_noun,
|
|
tab_id,
|
|
total
|
|
);
|
|
}
|
|
return;
|
|
}
|
|
}
|
|
// Console logs
|
|
if let Some(logs) = data.get("messages").and_then(|v| v.as_array()) {
|
|
if opts.content_boundaries {
|
|
let mut console_output = String::new();
|
|
for log in logs {
|
|
let level = log.get("type").and_then(|v| v.as_str()).unwrap_or("log");
|
|
let text = log.get("text").and_then(|v| v.as_str()).unwrap_or("");
|
|
console_output.push_str(&format!(
|
|
"{} {}\n",
|
|
color::console_level_prefix(level),
|
|
text
|
|
));
|
|
}
|
|
if console_output.ends_with('\n') {
|
|
console_output.pop();
|
|
}
|
|
print_with_boundaries(&console_output, origin, opts);
|
|
} else {
|
|
for log in logs {
|
|
let level = log.get("type").and_then(|v| v.as_str()).unwrap_or("log");
|
|
let text = log.get("text").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!("{} {}", color::console_level_prefix(level), text);
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
// Errors
|
|
if let Some(errors) = data.get("errors").and_then(|v| v.as_array()) {
|
|
for err in errors {
|
|
let msg = err.get("message").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!("{} {}", color::error_indicator(), msg);
|
|
}
|
|
return;
|
|
}
|
|
// Cookies
|
|
if let Some(cookies) = data.get("cookies").and_then(|v| v.as_array()) {
|
|
for cookie in cookies {
|
|
let name = cookie.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
let value = cookie.get("value").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!("{}={}", name, value);
|
|
}
|
|
return;
|
|
}
|
|
// Network requests
|
|
if let Some(requests) = data.get("requests").and_then(|v| v.as_array()) {
|
|
// Stamp the page these requests were read from, mirroring `eval @ url`,
|
|
// so a read against a drifted/wrong tab is obvious (issue #8.1).
|
|
if let Some(o) = data
|
|
.get("origin")
|
|
.and_then(|v| v.as_str())
|
|
.filter(|o| !o.is_empty())
|
|
{
|
|
eprintln!("network @ {o}");
|
|
}
|
|
if requests.is_empty() {
|
|
println!("No requests captured");
|
|
} else {
|
|
for req in requests {
|
|
let method = req.get("method").and_then(|v| v.as_str()).unwrap_or("GET");
|
|
let url = req.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
let resource_type = req
|
|
.get("resourceType")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let request_id = req.get("requestId").and_then(|v| v.as_str()).unwrap_or("");
|
|
let status = req.get("status").and_then(|v| v.as_i64());
|
|
match status {
|
|
Some(s) => println!(
|
|
"[{}] {} {} ({}) {}",
|
|
request_id, method, url, resource_type, s
|
|
),
|
|
None => println!("[{}] {} {} ({})", request_id, method, url, resource_type),
|
|
}
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
// Cleared (cookies, console, or request log)
|
|
if let Some(cleared) = data.get("cleared").and_then(|v| v.as_bool()) {
|
|
if cleared {
|
|
let label = match action {
|
|
Some("cookies_clear") => "Cookies cleared",
|
|
Some("console") => "Console log cleared",
|
|
_ => "Request log cleared",
|
|
};
|
|
println!("{} {}", color::success_indicator(), label);
|
|
return;
|
|
}
|
|
}
|
|
// Bounding box
|
|
if let Some(box_data) = data.get("box") {
|
|
println!(
|
|
"{}",
|
|
serde_json::to_string_pretty(box_data).unwrap_or_default()
|
|
);
|
|
return;
|
|
}
|
|
// Element styles
|
|
if let Some(elements) = data.get("elements").and_then(|v| v.as_array()) {
|
|
for (i, el) in elements.iter().enumerate() {
|
|
let tag = el.get("tag").and_then(|v| v.as_str()).unwrap_or("?");
|
|
let text = el.get("text").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!("[{}] {} \"{}\"", i, tag, text);
|
|
|
|
if let Some(box_data) = el.get("box") {
|
|
let w = box_data.get("width").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let h = box_data.get("height").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let x = box_data.get("x").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let y = box_data.get("y").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
println!(" box: {}x{} at ({}, {})", w, h, x, y);
|
|
}
|
|
|
|
if let Some(styles) = el.get("styles") {
|
|
let font_size = styles
|
|
.get("fontSize")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let font_weight = styles
|
|
.get("fontWeight")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let font_family = styles
|
|
.get("fontFamily")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let color = styles.get("color").and_then(|v| v.as_str()).unwrap_or("");
|
|
let bg = styles
|
|
.get("backgroundColor")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let radius = styles
|
|
.get("borderRadius")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
|
|
println!(" font: {} {} {}", font_size, font_weight, font_family);
|
|
println!(" color: {}", color);
|
|
println!(" background: {}", bg);
|
|
if radius != "0px" {
|
|
println!(" border-radius: {}", radius);
|
|
}
|
|
}
|
|
println!();
|
|
}
|
|
return;
|
|
}
|
|
// Closed (browser or tab)
|
|
if data.get("closed").is_some() {
|
|
let label = match action {
|
|
Some("tab_close") => {
|
|
if let Some(closed_id) = data.get("tabId").and_then(|v| v.as_str()) {
|
|
println!("{} Tab [{}] closed", color::success_indicator(), closed_id);
|
|
return;
|
|
}
|
|
"Tab closed"
|
|
}
|
|
_ => "Browser closed",
|
|
};
|
|
println!("{} {}", color::success_indicator(), label);
|
|
return;
|
|
}
|
|
// Started actions (profiling, HAR, recording)
|
|
if let Some(started) = data.get("started").and_then(|v| v.as_bool()) {
|
|
if started {
|
|
match action {
|
|
Some("profiler_start") => {
|
|
println!("{} Profiling started", color::success_indicator());
|
|
}
|
|
Some("har_start") => {
|
|
println!("{} HAR recording started", color::success_indicator());
|
|
}
|
|
_ => {
|
|
if let Some(path) = data.get("path").and_then(|v| v.as_str()) {
|
|
println!("{} Recording started: {}", color::success_indicator(), path);
|
|
} else {
|
|
println!("{} Recording started", color::success_indicator());
|
|
}
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
}
|
|
// Recording restart (has "stopped" field - from recording_restart action)
|
|
if data.get("stopped").is_some() {
|
|
let path = data
|
|
.get("path")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("unknown");
|
|
if let Some(prev_path) = data.get("previousPath").and_then(|v| v.as_str()) {
|
|
println!(
|
|
"{} Recording restarted: {} (previous saved to {})",
|
|
color::success_indicator(),
|
|
path,
|
|
prev_path
|
|
);
|
|
} else {
|
|
println!("{} Recording started: {}", color::success_indicator(), path);
|
|
}
|
|
return;
|
|
}
|
|
// Recording stop (has "frames" field - from recording_stop action)
|
|
if data.get("frames").is_some() {
|
|
if let Some(path) = data.get("path").and_then(|v| v.as_str()) {
|
|
if let Some(error) = data.get("error").and_then(|v| v.as_str()) {
|
|
println!(
|
|
"{} Recording saved to {} - {}",
|
|
color::warning_indicator(),
|
|
path,
|
|
error
|
|
);
|
|
} else {
|
|
println!("{} Recording saved to {}", color::success_indicator(), path);
|
|
}
|
|
} else {
|
|
println!("{} Recording stopped", color::success_indicator());
|
|
}
|
|
return;
|
|
}
|
|
// Download response (has "suggestedFilename" or "filename" field)
|
|
if data.get("suggestedFilename").is_some() || data.get("filename").is_some() {
|
|
if let Some(path) = data.get("path").and_then(|v| v.as_str()) {
|
|
let filename = data
|
|
.get("suggestedFilename")
|
|
.or_else(|| data.get("filename"))
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
if filename.is_empty() {
|
|
println!(
|
|
"{} Downloaded to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
);
|
|
} else {
|
|
println!(
|
|
"{} Downloaded to {} ({})",
|
|
color::success_indicator(),
|
|
color::green(path),
|
|
filename
|
|
);
|
|
}
|
|
return;
|
|
}
|
|
}
|
|
// Trace stop without path
|
|
if data.get("traceStopped").is_some() {
|
|
println!("{} Trace stopped", color::success_indicator());
|
|
return;
|
|
}
|
|
// Path-based operations (screenshot/pdf/trace/har/download/state/video)
|
|
if let Some(path) = data.get("path").and_then(|v| v.as_str()) {
|
|
match action.unwrap_or("") {
|
|
"screenshot" => {
|
|
println!(
|
|
"{} Screenshot saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
);
|
|
// Stamp which page was captured (mirrors `eval @ url`) so a
|
|
// screenshot of the wrong/drifted tab is obvious (issue #8.1).
|
|
if let Some(o) = data
|
|
.get("origin")
|
|
.and_then(|v| v.as_str())
|
|
.filter(|o| !o.is_empty())
|
|
{
|
|
eprintln!("screenshot @ {o}");
|
|
}
|
|
if let Some(annotations) = data.get("annotations").and_then(|v| v.as_array()) {
|
|
// Cap the printed legend on dense pages (it can be
|
|
// hundreds of lines and flood the terminal). The image
|
|
// still shows every marker; --json returns the full list.
|
|
const LEGEND_CAP: usize = 40;
|
|
let total = annotations.len();
|
|
for ann in annotations.iter().take(LEGEND_CAP) {
|
|
let num = ann.get("number").and_then(|n| n.as_u64()).unwrap_or(0);
|
|
let ref_id = ann.get("ref").and_then(|r| r.as_str()).unwrap_or("");
|
|
let role = ann.get("role").and_then(|r| r.as_str()).unwrap_or("");
|
|
let name = ann.get("name").and_then(|n| n.as_str()).unwrap_or("");
|
|
if name.is_empty() {
|
|
println!(
|
|
" {} @{} {}",
|
|
color::dim(&format!("[{}]", num)),
|
|
ref_id,
|
|
role,
|
|
);
|
|
} else {
|
|
println!(
|
|
" {} @{} {} {:?}",
|
|
color::dim(&format!("[{}]", num)),
|
|
ref_id,
|
|
role,
|
|
name,
|
|
);
|
|
}
|
|
}
|
|
if total > LEGEND_CAP {
|
|
println!(
|
|
" {}",
|
|
color::dim(&format!(
|
|
"… and {} more markers (shown in the image; --json for the full list)",
|
|
total - LEGEND_CAP
|
|
))
|
|
);
|
|
}
|
|
}
|
|
}
|
|
"pdf" => println!(
|
|
"{} PDF saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
),
|
|
"trace_stop" => println!(
|
|
"{} Trace saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
),
|
|
"profiler_stop" => println!(
|
|
"{} Profile saved to {} ({} events)",
|
|
color::success_indicator(),
|
|
color::green(path),
|
|
data.get("eventCount").and_then(|c| c.as_u64()).unwrap_or(0)
|
|
),
|
|
"har_stop" => println!(
|
|
"{} HAR saved to {} ({} requests)",
|
|
color::success_indicator(),
|
|
color::green(path),
|
|
data.get("requestCount")
|
|
.and_then(|c| c.as_u64())
|
|
.unwrap_or(0)
|
|
),
|
|
"download" | "waitfordownload" => println!(
|
|
"{} Download saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
),
|
|
"video_stop" => println!(
|
|
"{} Video saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
),
|
|
"state_save" => println!(
|
|
"{} State saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
),
|
|
"state_load" => {
|
|
if let Some(note) = data.get("note").and_then(|v| v.as_str()) {
|
|
println!("{}", note);
|
|
}
|
|
println!(
|
|
"{} State path set to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
);
|
|
}
|
|
// video_start and other commands that provide a path with a note
|
|
"video_start" => {
|
|
if let Some(note) = data.get("note").and_then(|v| v.as_str()) {
|
|
println!("{}", note);
|
|
}
|
|
println!("Path: {}", path);
|
|
}
|
|
_ => println!(
|
|
"{} Saved to {}",
|
|
color::success_indicator(),
|
|
color::green(path)
|
|
),
|
|
}
|
|
return;
|
|
}
|
|
|
|
// State list
|
|
if let Some(files) = data.get("files").and_then(|v| v.as_array()) {
|
|
if let Some(dir) = data.get("directory").and_then(|v| v.as_str()) {
|
|
println!("{}", color::bold(&format!("Saved states in {}", dir)));
|
|
}
|
|
if files.is_empty() {
|
|
println!("{}", color::dim(" No state files found"));
|
|
} else {
|
|
for file in files {
|
|
let filename = file.get("filename").and_then(|v| v.as_str()).unwrap_or("");
|
|
let size = file.get("size").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let modified = file.get("modified").and_then(|v| v.as_str()).unwrap_or("");
|
|
let encrypted = file
|
|
.get("encrypted")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
let size_str = if size > 1024 {
|
|
format!("{:.1}KB", size as f64 / 1024.0)
|
|
} else {
|
|
format!("{}B", size)
|
|
};
|
|
let date_str = modified.split('T').next().unwrap_or(modified);
|
|
let enc_str = if encrypted { " [encrypted]" } else { "" };
|
|
println!(
|
|
" {} {}",
|
|
filename,
|
|
color::dim(&format!("({}, {}){}", size_str, date_str, enc_str))
|
|
);
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
|
|
// State rename
|
|
if let Some(true) = data.get("renamed").and_then(|v| v.as_bool()) {
|
|
let old_name = data.get("oldName").and_then(|v| v.as_str()).unwrap_or("");
|
|
let new_name = data.get("newName").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(
|
|
"{} Renamed {} -> {}",
|
|
color::success_indicator(),
|
|
old_name,
|
|
new_name
|
|
);
|
|
return;
|
|
}
|
|
|
|
// State clear
|
|
if let Some(cleared) = data.get("cleared").and_then(|v| v.as_i64()) {
|
|
println!(
|
|
"{} Cleared {} state file(s)",
|
|
color::success_indicator(),
|
|
cleared
|
|
);
|
|
return;
|
|
}
|
|
|
|
// State show summary
|
|
if let Some(summary) = data.get("summary") {
|
|
let cookies = summary.get("cookies").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let origins = summary.get("origins").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let encrypted = data
|
|
.get("encrypted")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
let enc_str = if encrypted { " (encrypted)" } else { "" };
|
|
println!("State file summary{}:", enc_str);
|
|
println!(" Cookies: {}", cookies);
|
|
println!(" Origins with localStorage: {}", origins);
|
|
return;
|
|
}
|
|
|
|
// State clean
|
|
if let Some(cleaned) = data.get("cleaned").and_then(|v| v.as_i64()) {
|
|
println!(
|
|
"{} Cleaned {} old state file(s)",
|
|
color::success_indicator(),
|
|
cleaned
|
|
);
|
|
return;
|
|
}
|
|
|
|
// Informational note
|
|
if let Some(note) = data.get("note").and_then(|v| v.as_str()) {
|
|
println!("{}", note);
|
|
return;
|
|
}
|
|
// Auth list
|
|
if let Some(profiles) = data.get("profiles").and_then(|v| v.as_array()) {
|
|
if profiles.is_empty() {
|
|
println!("{}", color::dim("No auth profiles saved"));
|
|
} else {
|
|
println!("{}", color::bold("Auth profiles:"));
|
|
for p in profiles {
|
|
let name = p.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
let url = p.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
let user = p.get("username").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(
|
|
" {} {} {}",
|
|
color::green(name),
|
|
color::dim(user),
|
|
color::dim(url)
|
|
);
|
|
}
|
|
}
|
|
return;
|
|
}
|
|
|
|
// Auth show
|
|
if let Some(profile) = data.get("profile").and_then(|v| v.as_object()) {
|
|
let name = profile.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
let url = profile.get("url").and_then(|v| v.as_str()).unwrap_or("");
|
|
let user = profile
|
|
.get("username")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let created = profile
|
|
.get("createdAt")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let last_login = profile.get("lastLoginAt").and_then(|v| v.as_str());
|
|
println!("Name: {}", name);
|
|
println!("URL: {}", url);
|
|
println!("Username: {}", user);
|
|
println!("Created: {}", created);
|
|
if let Some(ll) = last_login {
|
|
println!("Last login: {}", ll);
|
|
}
|
|
return;
|
|
}
|
|
|
|
// Auth save/update/login/delete
|
|
if data.get("saved").and_then(|v| v.as_bool()).unwrap_or(false) {
|
|
let name = data.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(
|
|
"{} Auth profile '{}' saved",
|
|
color::success_indicator(),
|
|
name
|
|
);
|
|
return;
|
|
}
|
|
if data
|
|
.get("updated")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
&& !data.get("saved").and_then(|v| v.as_bool()).unwrap_or(false)
|
|
{
|
|
let name = data.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
println!(
|
|
"{} Auth profile '{}' updated",
|
|
color::success_indicator(),
|
|
name
|
|
);
|
|
return;
|
|
}
|
|
if data
|
|
.get("loggedIn")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
{
|
|
let name = data.get("name").and_then(|v| v.as_str()).unwrap_or("");
|
|
if let Some(title) = data.get("title").and_then(|v| v.as_str()) {
|
|
println!(
|
|
"{} Logged in as '{}' - {}",
|
|
color::success_indicator(),
|
|
name,
|
|
title
|
|
);
|
|
} else {
|
|
println!("{} Logged in as '{}'", color::success_indicator(), name);
|
|
}
|
|
return;
|
|
}
|
|
if data
|
|
.get("deleted")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
{
|
|
if let Some(name) = data.get("name").and_then(|v| v.as_str()) {
|
|
println!(
|
|
"{} Auth profile '{}' deleted",
|
|
color::success_indicator(),
|
|
name
|
|
);
|
|
return;
|
|
}
|
|
}
|
|
|
|
// Confirmation required (for orchestrator use)
|
|
if data
|
|
.get("confirmation_required")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
{
|
|
let category = data.get("category").and_then(|v| v.as_str()).unwrap_or("");
|
|
let description = data
|
|
.get("description")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
let cid = data
|
|
.get("confirmation_id")
|
|
.and_then(|v| v.as_str())
|
|
.unwrap_or("");
|
|
println!("Confirmation required:");
|
|
println!(" {}: {}", category, description);
|
|
println!(" Run: chrome-use confirm {}", cid);
|
|
println!(" Or: chrome-use deny {}", cid);
|
|
return;
|
|
}
|
|
if data
|
|
.get("confirmed")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
{
|
|
println!("{} Action confirmed", color::success_indicator());
|
|
return;
|
|
}
|
|
if data
|
|
.get("denied")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false)
|
|
{
|
|
println!("{} Action denied", color::success_indicator());
|
|
return;
|
|
}
|
|
|
|
// Default success
|
|
println!("{} Done", color::success_indicator());
|
|
} else {
|
|
// Success response with no data payload — still confirm the command ran
|
|
// instead of printing nothing (a silent exit 0 looks like a no-op and
|
|
// hides whether anything happened).
|
|
println!("{} Done", color::success_indicator());
|
|
}
|
|
|
|
print_warning(resp);
|
|
}
|
|
|
|
fn print_warning(resp: &Response) {
|
|
if let Some(ref warning) = resp.warning {
|
|
eprintln!("{} {}", color::warning_indicator(), warning);
|
|
}
|
|
}
|
|
|
|
/// Print command-specific help. Returns true if help was printed, false if command unknown.
|
|
pub fn print_command_help(command: &str) -> bool {
|
|
let help = match command {
|
|
// === Navigation ===
|
|
"open" | "goto" | "navigate" => {
|
|
r##"
|
|
chrome-use open - Launch the browser, optionally navigate
|
|
|
|
Usage: chrome-use open [url]
|
|
|
|
Without a URL, launches the browser but stays on about:blank. This lets
|
|
you stage state (network routes, cookies, init scripts) before the first
|
|
real navigation — useful for SSR debug, auth setup, and capturing fresh
|
|
`react suspense` / `vitals` state without noise from a prior page.
|
|
|
|
With a URL, launches and navigates. If no protocol is provided, https://
|
|
is automatically prepended.
|
|
|
|
The `goto` and `navigate` aliases still require a URL.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
--headers <json> Set HTTP headers (scoped to this origin)
|
|
--headed Show browser window (default; headless is forbidden — it's a bot tell)
|
|
--enable react-devtools Inject the React DevTools hook before any page JS
|
|
--init-script <path> Register a page init script (repeatable)
|
|
|
|
Examples:
|
|
chrome-use open # Launch, no nav
|
|
chrome-use open example.com
|
|
chrome-use open https://github.com
|
|
chrome-use open localhost:3000
|
|
chrome-use open api.example.com --headers '{"Authorization": "Bearer token"}'
|
|
# ^ Headers only sent to api.example.com, not other domains
|
|
|
|
# Pre-navigation setup in one turn:
|
|
chrome-use batch \
|
|
'["open"]' \
|
|
'["network","route","*","--abort","--resource-type","script"]' \
|
|
'["navigate","http://localhost:3000/target"]'
|
|
"##
|
|
}
|
|
"back" => {
|
|
r##"
|
|
chrome-use back - Navigate back in history
|
|
|
|
Usage: chrome-use back
|
|
|
|
Goes back one page in the browser history, equivalent to clicking
|
|
the browser's back button.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use back
|
|
"##
|
|
}
|
|
"forward" => {
|
|
r##"
|
|
chrome-use forward - Navigate forward in history
|
|
|
|
Usage: chrome-use forward
|
|
|
|
Goes forward one page in the browser history, equivalent to clicking
|
|
the browser's forward button.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use forward
|
|
"##
|
|
}
|
|
"reload" => {
|
|
r##"
|
|
chrome-use reload - Reload the current page
|
|
|
|
Usage: chrome-use reload
|
|
|
|
Reloads the current page, equivalent to pressing F5 or clicking
|
|
the browser's reload button.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use reload
|
|
"##
|
|
}
|
|
|
|
// === Core Actions ===
|
|
"click" => {
|
|
r##"
|
|
chrome-use click - Click an element or a coordinate
|
|
|
|
Usage: chrome-use click <selector> [--new-tab]
|
|
chrome-use click <x> <y> | <x>,<y> | --coords <x>,<y>
|
|
|
|
Clicks on the specified element. The selector can be a CSS selector,
|
|
XPath, or an element reference from snapshot (e.g., @e1).
|
|
|
|
A bare-number argument is treated as a viewport coordinate, not a
|
|
selector — `click 449 320` clicks the pixel point (no element needed).
|
|
|
|
Options:
|
|
--coords <x>,<y> Click a viewport coordinate (explicit form)
|
|
--new-tab Open link in a new tab instead of navigating current tab
|
|
(only works on elements with href attribute)
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use click "#submit-button"
|
|
chrome-use click @e1
|
|
chrome-use click "button.primary"
|
|
chrome-use click "//button[@type='submit']"
|
|
chrome-use click @e3 --new-tab
|
|
"##
|
|
}
|
|
"dblclick" => {
|
|
r##"
|
|
chrome-use dblclick - Double-click an element
|
|
|
|
Usage: chrome-use dblclick <selector>
|
|
|
|
Double-clicks on the specified element. Useful for text selection
|
|
or triggering double-click handlers.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use dblclick "#editable-text"
|
|
chrome-use dblclick @e5
|
|
"##
|
|
}
|
|
"fill" => {
|
|
r##"
|
|
chrome-use fill - Clear and fill an input field
|
|
|
|
Usage: chrome-use fill <selector> <text>
|
|
|
|
Clears the input field and fills it with the specified text.
|
|
This replaces any existing content in the field.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use fill "#email" "user@example.com"
|
|
chrome-use fill @e3 "Hello World"
|
|
chrome-use fill "input[name='search']" "query"
|
|
"##
|
|
}
|
|
"type" => {
|
|
r##"
|
|
chrome-use type - Type text into an element
|
|
|
|
Usage: chrome-use type <selector> <text>
|
|
|
|
Types text into the specified element character by character.
|
|
Unlike fill, this does not clear existing content first.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use type "#search" "hello"
|
|
chrome-use type @e2 "additional text"
|
|
|
|
See Also:
|
|
For typing into contenteditable editors (Lexical, ProseMirror, etc.)
|
|
without a selector, use 'keyboard type' instead:
|
|
chrome-use keyboard type "# My Heading"
|
|
"##
|
|
}
|
|
"hover" => {
|
|
r##"
|
|
chrome-use hover - Hover over an element
|
|
|
|
Usage: chrome-use hover <selector>
|
|
|
|
Moves the mouse to hover over the specified element. Useful for
|
|
triggering hover states or dropdown menus.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use hover "#dropdown-trigger"
|
|
chrome-use hover @e4
|
|
"##
|
|
}
|
|
"focus" => {
|
|
r##"
|
|
chrome-use focus - Focus an element
|
|
|
|
Usage: chrome-use focus <selector>
|
|
|
|
Sets keyboard focus to the specified element.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use focus "#input-field"
|
|
chrome-use focus @e2
|
|
"##
|
|
}
|
|
"check" => {
|
|
r##"
|
|
chrome-use check - Check a checkbox
|
|
|
|
Usage: chrome-use check <selector>
|
|
|
|
Checks a checkbox element. If already checked, no action is taken.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use check "#terms-checkbox"
|
|
chrome-use check @e7
|
|
"##
|
|
}
|
|
"uncheck" => {
|
|
r##"
|
|
chrome-use uncheck - Uncheck a checkbox
|
|
|
|
Usage: chrome-use uncheck <selector>
|
|
|
|
Unchecks a checkbox element. If already unchecked, no action is taken.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use uncheck "#newsletter-opt-in"
|
|
chrome-use uncheck @e8
|
|
"##
|
|
}
|
|
"select" => {
|
|
r##"
|
|
chrome-use select - Select a dropdown option
|
|
|
|
Usage: chrome-use select <selector> <value...>
|
|
|
|
Selects one or more options in a <select> dropdown by value.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use select "#country" "US"
|
|
chrome-use select @e5 "option2"
|
|
chrome-use select "#menu" "opt1" "opt2" "opt3"
|
|
"##
|
|
}
|
|
"drag" => {
|
|
r##"
|
|
chrome-use drag - Drag and drop
|
|
|
|
Usage: chrome-use drag <source> <target>
|
|
|
|
Drags an element from source to target location.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use drag "#draggable" "#drop-zone"
|
|
chrome-use drag @e1 @e2
|
|
"##
|
|
}
|
|
"upload" => {
|
|
r##"
|
|
chrome-use upload - Upload files
|
|
|
|
Usage: chrome-use upload <selector> <files...>
|
|
|
|
Uploads one or more files to a file input element.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use upload "#file-input" ./document.pdf
|
|
chrome-use upload @e3 ./image1.png ./image2.png
|
|
"##
|
|
}
|
|
"download" => {
|
|
r##"
|
|
chrome-use download - Download a file by clicking an element
|
|
|
|
Usage: chrome-use download <selector> <path>
|
|
|
|
Clicks an element that triggers a download and saves the file to the specified path.
|
|
|
|
Arguments:
|
|
selector Element to click (CSS selector or @ref)
|
|
path Path where the downloaded file will be saved
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use download "#download-btn" ./file.pdf
|
|
chrome-use download @e5 ./report.xlsx
|
|
chrome-use download "a[href$='.zip']" ./archive.zip
|
|
"##
|
|
}
|
|
|
|
// === Keyboard ===
|
|
"press" | "key" => {
|
|
r##"
|
|
chrome-use press - Press a key or key combination
|
|
|
|
Usage: chrome-use press <key>
|
|
|
|
Presses a key or key combination. Supports special keys and modifiers.
|
|
|
|
Aliases: key
|
|
|
|
Special Keys:
|
|
Enter, Tab, Escape, Backspace, Delete, Space
|
|
ArrowUp, ArrowDown, ArrowLeft, ArrowRight
|
|
Home, End, PageUp, PageDown
|
|
F1-F12
|
|
|
|
Modifiers (combine with +):
|
|
Control, Alt, Shift, Meta
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use press Enter
|
|
chrome-use press Tab
|
|
chrome-use press Control+a
|
|
chrome-use press Control+Shift+s
|
|
chrome-use press Escape
|
|
"##
|
|
}
|
|
"keydown" => {
|
|
r##"
|
|
chrome-use keydown - Press a key down (without release)
|
|
|
|
Usage: chrome-use keydown <key>
|
|
|
|
Presses a key down without releasing it. Use keyup to release.
|
|
Useful for holding modifier keys.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use keydown Shift
|
|
chrome-use keydown Control
|
|
"##
|
|
}
|
|
"keyup" => {
|
|
r##"
|
|
chrome-use keyup - Release a key
|
|
|
|
Usage: chrome-use keyup <key>
|
|
|
|
Releases a key that was pressed with keydown.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use keyup Shift
|
|
chrome-use keyup Control
|
|
"##
|
|
}
|
|
"keyboard" => {
|
|
r##"
|
|
chrome-use keyboard - Raw keyboard input (no selector needed)
|
|
|
|
Usage: chrome-use keyboard <subcommand> <text>
|
|
|
|
Sends keyboard input to whatever element currently has focus.
|
|
Unlike 'type' which requires a selector, 'keyboard' operates on
|
|
the current focus — essential for contenteditable editors like
|
|
Lexical, ProseMirror, CodeMirror, and Monaco.
|
|
|
|
Subcommands:
|
|
type <text> Type text character-by-character with real
|
|
key events (keydown, keypress, keyup per char)
|
|
inserttext <text> Insert text without key events (like paste)
|
|
|
|
Note: For key combos (Enter, Control+a), use the 'press' command
|
|
directly — it already operates on the current focus.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use keyboard type "Hello, World!"
|
|
chrome-use keyboard type "# My Heading"
|
|
chrome-use keyboard inserttext "pasted content"
|
|
|
|
Use Cases:
|
|
# Type into a Lexical/ProseMirror contenteditable editor:
|
|
chrome-use click "[contenteditable]"
|
|
chrome-use keyboard type "# My Heading"
|
|
chrome-use press Enter
|
|
chrome-use keyboard type "Some paragraph text"
|
|
"##
|
|
}
|
|
|
|
// === Scroll ===
|
|
"scroll" => {
|
|
r##"
|
|
chrome-use scroll - Scroll the page
|
|
|
|
Usage: chrome-use scroll [direction] [amount] [options]
|
|
|
|
Scrolls the page or a specific element in the specified direction.
|
|
|
|
Arguments:
|
|
direction up, down, left, right (default: down)
|
|
amount Pixels to scroll (default: 300)
|
|
|
|
Options:
|
|
-s, --selector <sel> CSS selector for a scrollable container
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use scroll
|
|
chrome-use scroll down 500
|
|
chrome-use scroll up 200
|
|
chrome-use scroll left 100
|
|
chrome-use scroll down 500 --selector "div.scroll-container"
|
|
"##
|
|
}
|
|
"scrollintoview" | "scrollinto" => {
|
|
r##"
|
|
chrome-use scrollintoview - Scroll element into view
|
|
|
|
Usage: chrome-use scrollintoview <selector>
|
|
|
|
Scrolls the page until the specified element is visible in the viewport.
|
|
|
|
Aliases: scrollinto
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use scrollintoview "#footer"
|
|
chrome-use scrollintoview @e15
|
|
"##
|
|
}
|
|
|
|
// === Wait ===
|
|
"wait" => {
|
|
r##"
|
|
chrome-use wait - Wait for condition
|
|
|
|
Usage: chrome-use wait <selector|ms|option>
|
|
|
|
Waits for an element to appear, a timeout, or other conditions.
|
|
|
|
Modes:
|
|
<selector> Wait for element to appear
|
|
<ms> Wait for specified milliseconds
|
|
--url <pattern> Wait for URL to match pattern
|
|
--load <state> Wait for load state (load, domcontentloaded, networkidle)
|
|
--fn <expression> Wait for JavaScript expression to be truthy
|
|
--text <text> Wait for text to appear on page (substring match)
|
|
--download [path] Wait for a download to complete (optionally save to path)
|
|
|
|
Download Options (with --download):
|
|
--timeout <ms> Timeout in milliseconds for download to start
|
|
|
|
Wait for text to disappear:
|
|
Use --fn or --state hidden to wait for text or elements to go away:
|
|
wait --fn "!document.body.innerText.includes('Loading...')"
|
|
wait "#spinner" --state hidden
|
|
wait @e5 --state detached
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use wait "#loading-spinner"
|
|
chrome-use wait 2000
|
|
chrome-use wait --url "**/dashboard"
|
|
chrome-use wait --load networkidle
|
|
chrome-use wait --fn "window.appReady === true"
|
|
chrome-use wait --text "Welcome back"
|
|
chrome-use wait --download ./file.pdf
|
|
chrome-use wait --download ./report.xlsx --timeout 30000
|
|
chrome-use wait --fn "!document.body.innerText.includes('Loading...')"
|
|
"##
|
|
}
|
|
|
|
// === Screenshot/PDF ===
|
|
"screenshot" => {
|
|
r##"
|
|
chrome-use screenshot - Take a screenshot
|
|
|
|
Usage: chrome-use screenshot [selector] [path]
|
|
|
|
Captures a screenshot of the current page. If no path is provided,
|
|
saves to a temporary directory with a generated filename.
|
|
Headless Chromium screenshots hide native scrollbars for consistent image output.
|
|
Pass --hide-scrollbars false when launching to keep native scrollbars visible.
|
|
|
|
Options:
|
|
--full, -f Capture full page (not just viewport)
|
|
--annotate Overlay numbered labels on interactive elements.
|
|
Each label [N] corresponds to ref @eN from snapshot.
|
|
Prints a legend mapping labels to element roles/names.
|
|
With --json, annotations are included in the response.
|
|
Supported on Chromium and Lightpanda.
|
|
--screenshot-dir <path> Default output directory for screenshots
|
|
(or AGENT_BROWSER_SCREENSHOT_DIR env)
|
|
--screenshot-quality <0-100> JPEG quality (0-100, only applies to jpeg format)
|
|
(or AGENT_BROWSER_SCREENSHOT_QUALITY env)
|
|
--screenshot-format <fmt> Image format: png (default) or jpeg
|
|
(or AGENT_BROWSER_SCREENSHOT_FORMAT env)
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use screenshot
|
|
chrome-use screenshot ./screenshot.png
|
|
chrome-use screenshot --full ./full-page.png
|
|
chrome-use screenshot --annotate # Labeled screenshot + legend
|
|
chrome-use screenshot --annotate ./page.png # Save annotated screenshot
|
|
chrome-use screenshot --annotate --json # JSON output with annotations
|
|
chrome-use screenshot --screenshot-dir ./shots # Save to custom directory
|
|
chrome-use screenshot --screenshot-format jpeg --screenshot-quality 80
|
|
"##
|
|
}
|
|
"pdf" => {
|
|
r##"
|
|
chrome-use pdf - Save page as PDF
|
|
|
|
Usage: chrome-use pdf <path>
|
|
|
|
Saves the current page as a PDF file.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use pdf ./page.pdf
|
|
chrome-use pdf ~/Documents/report.pdf
|
|
"##
|
|
}
|
|
|
|
// === Snapshot ===
|
|
"snapshot" => {
|
|
r##"
|
|
chrome-use snapshot - Get accessibility tree snapshot
|
|
|
|
Usage: chrome-use snapshot [options]
|
|
|
|
Returns an accessibility tree representation of the page with element
|
|
references (like @e1, @e2) that can be used in subsequent commands.
|
|
Designed for AI agents to understand page structure.
|
|
|
|
Options:
|
|
-i, --interactive Only include interactive elements
|
|
-u, --urls Include href URLs for link elements
|
|
-c, --compact Remove empty structural elements
|
|
-d, --depth <n> Limit tree depth
|
|
-s, --selector <sel> Scope snapshot to CSS selector
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use snapshot
|
|
chrome-use snapshot -i
|
|
chrome-use snapshot -i --urls
|
|
chrome-use snapshot --compact --depth 5
|
|
chrome-use snapshot -s "#main-content"
|
|
"##
|
|
}
|
|
|
|
// === Eval ===
|
|
"eval" => {
|
|
r##"
|
|
chrome-use eval - Execute JavaScript
|
|
|
|
Usage: chrome-use eval [options] <script>
|
|
|
|
Executes JavaScript code in the browser context and returns the result.
|
|
|
|
Options:
|
|
-b, --base64 Decode script from base64 (avoids shell escaping issues)
|
|
--stdin Read script from stdin (useful for heredocs/multiline)
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use eval "document.title"
|
|
chrome-use eval "window.location.href"
|
|
chrome-use eval "document.querySelectorAll('a').length"
|
|
chrome-use eval -b "ZG9jdW1lbnQudGl0bGU="
|
|
|
|
# Read from stdin with heredoc
|
|
cat <<'EOF' | chrome-use eval --stdin
|
|
const links = document.querySelectorAll('a');
|
|
links.length;
|
|
EOF
|
|
"##
|
|
}
|
|
|
|
// === Close ===
|
|
"close" | "quit" | "exit" => {
|
|
r##"
|
|
chrome-use close - Close the browser
|
|
|
|
Usage: chrome-use close [options]
|
|
|
|
Closes the browser instance for the current session.
|
|
|
|
Aliases: quit, exit
|
|
|
|
Options:
|
|
--all Close all active sessions
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use close
|
|
chrome-use close --session mysession
|
|
chrome-use close --all
|
|
"##
|
|
}
|
|
|
|
// === Inspect ===
|
|
"inspect" => {
|
|
r##"
|
|
chrome-use inspect - Open Chrome DevTools for the active page
|
|
|
|
Starts a local WebSocket proxy and opens Chrome's DevTools frontend in your
|
|
default browser. The proxy routes DevTools traffic through the daemon's
|
|
existing CDP connection, so both DevTools and chrome-use commands work
|
|
simultaneously.
|
|
|
|
Usage: chrome-use inspect
|
|
|
|
Examples:
|
|
chrome-use open example.com
|
|
chrome-use inspect # opens DevTools in your browser
|
|
chrome-use click "Submit" # commands still work while DevTools is open
|
|
"##
|
|
}
|
|
|
|
// === Get ===
|
|
"get" => {
|
|
r##"
|
|
chrome-use get - Retrieve information from elements or page
|
|
|
|
Usage: chrome-use get <subcommand> [args]
|
|
|
|
Retrieves various types of information from elements or the page.
|
|
|
|
Subcommands:
|
|
text [selector] Element text; no selector = WHOLE PAGE, all frames
|
|
text --main Main-content text only (skip nav/header/sidebar)
|
|
text --pierce Read through CLOSED shadow DOM (injected panels)
|
|
html <selector> Get inner HTML of element
|
|
value <selector> Get value of input element
|
|
attr <selector> <name> Get attribute value
|
|
title Get page title
|
|
url Get current URL
|
|
count <selector> Count matching elements
|
|
box <selector> Get bounding box (x, y, width, height)
|
|
styles <selector> Get computed styles of elements
|
|
cdp-url Get Chrome DevTools Protocol WebSocket URL
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use get text # whole page across ALL frames (default)
|
|
chrome-use get text @e1 # one element
|
|
chrome-use get text --main # main content, no nav/sidebar boilerplate
|
|
chrome-use frames # list frames + where the text lives
|
|
chrome-use get html "#content"
|
|
chrome-use get value "#email-input"
|
|
chrome-use get attr "#link" href
|
|
chrome-use get title
|
|
chrome-use get url
|
|
chrome-use get count "li.item"
|
|
chrome-use get box "#header"
|
|
chrome-use get styles "button"
|
|
chrome-use get styles @e1
|
|
"##
|
|
}
|
|
|
|
// === Is ===
|
|
"is" => {
|
|
r##"
|
|
chrome-use is - Check element state
|
|
|
|
Usage: chrome-use is <subcommand> <selector>
|
|
|
|
Checks the state of an element and returns true/false.
|
|
|
|
Subcommands:
|
|
visible <selector> Check if element is visible
|
|
enabled <selector> Check if element is enabled (not disabled)
|
|
checked <selector> Check if checkbox/radio is checked
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use is visible "#modal"
|
|
chrome-use is enabled "#submit-btn"
|
|
chrome-use is checked "#agree-checkbox"
|
|
"##
|
|
}
|
|
|
|
// === Find ===
|
|
"find" => {
|
|
r##"
|
|
chrome-use find - Find and interact with elements by locator
|
|
|
|
Usage: chrome-use find <locator> <value> [action] [text]
|
|
|
|
Finds elements using semantic locators and optionally performs an action.
|
|
|
|
Locators:
|
|
role <role> Find by ARIA role (--name <n>, --exact)
|
|
text <text> Find by text content (--exact)
|
|
label <label> Find by associated label (--exact)
|
|
placeholder <text> Find by placeholder text (--exact)
|
|
alt <text> Find by alt text (--exact)
|
|
title <text> Find by title attribute (--exact)
|
|
testid <id> Find by data-testid attribute
|
|
first <selector> First matching element
|
|
last <selector> Last matching element
|
|
nth <index> <selector> Nth matching element (0-based)
|
|
|
|
Actions (default: click):
|
|
click, fill, type, hover, focus, check, uncheck
|
|
|
|
Options:
|
|
--name <name> Filter role by accessible name
|
|
--exact Require exact text match
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use find role button click --name Submit
|
|
chrome-use find text "Sign In" click
|
|
chrome-use find label "Email" fill "user@example.com"
|
|
chrome-use find placeholder "Search..." type "query"
|
|
chrome-use find testid "login-form" click
|
|
chrome-use find first "li.item" click
|
|
chrome-use find nth 2 ".card" hover
|
|
"##
|
|
}
|
|
|
|
// === Mouse ===
|
|
"mouse" => {
|
|
r##"
|
|
chrome-use mouse - Low-level mouse operations
|
|
|
|
Usage: chrome-use mouse <subcommand> [args]
|
|
|
|
Performs low-level mouse operations for precise control.
|
|
|
|
Subcommands:
|
|
move <x> <y> Move mouse to coordinates
|
|
down [button] Press mouse button (left, right, middle)
|
|
up [button] Release mouse button
|
|
wheel <dy> [dx] Scroll mouse wheel
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use mouse move 100 200
|
|
chrome-use mouse down
|
|
chrome-use mouse up
|
|
chrome-use mouse down right
|
|
chrome-use mouse wheel 100
|
|
chrome-use mouse wheel -50 0
|
|
"##
|
|
}
|
|
|
|
// === Set ===
|
|
"set" => {
|
|
r##"
|
|
chrome-use set - Configure browser settings
|
|
|
|
Usage: chrome-use set <setting> [args]
|
|
|
|
Configures various browser settings and emulation options.
|
|
|
|
Settings:
|
|
viewport <w> <h> [scale] Set viewport size (scale = deviceScaleFactor, e.g. 2 for retina)
|
|
device <name> Emulate device (e.g., "iPhone 12")
|
|
geo <lat> <lng> Set geolocation
|
|
offline [on|off] Toggle offline mode
|
|
headers <json> Set extra HTTP headers
|
|
credentials <user> <pass> Set HTTP authentication
|
|
media [dark|light] Set color scheme preference
|
|
[reduced-motion] Enable reduced motion
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use set viewport 1920 1080
|
|
chrome-use set viewport 1920 1080 2 # 2x retina
|
|
chrome-use set device "iPhone 12"
|
|
chrome-use set geo 37.7749 -122.4194
|
|
chrome-use set offline on
|
|
chrome-use set headers '{"X-Custom": "value"}'
|
|
chrome-use set credentials admin secret123
|
|
chrome-use set media dark
|
|
chrome-use set media light reduced-motion
|
|
"##
|
|
}
|
|
|
|
// === Network ===
|
|
"network" => {
|
|
r##"
|
|
chrome-use network - Network interception and monitoring
|
|
|
|
Usage: chrome-use network <subcommand> [args]
|
|
|
|
Intercept, mock, or monitor network requests.
|
|
|
|
Subcommands:
|
|
route <url> [options] Intercept requests matching URL pattern
|
|
--abort Abort matching requests
|
|
--body <json> Respond with custom body
|
|
unroute [url] Remove route (all if no URL)
|
|
requests [options] List captured requests
|
|
--clear Clear request log
|
|
--filter <pattern> Filter by URL pattern
|
|
--type <types> Filter by resource type (comma-separated: xhr,fetch,document)
|
|
--method <method> Filter by HTTP method (GET, POST, etc.)
|
|
--status <code> Filter by status (200, 2xx, 400-499)
|
|
request <requestId> View full request/response detail (including body)
|
|
har <start|stop> [path] Record and export a HAR file
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use network route "**/api/*" --abort
|
|
chrome-use network route "**/data.json" --body '{"mock": true}'
|
|
chrome-use network unroute
|
|
chrome-use network requests
|
|
chrome-use network requests --filter "api"
|
|
chrome-use network requests --type xhr,fetch
|
|
chrome-use network requests --method POST --status 2xx
|
|
chrome-use network requests --clear
|
|
chrome-use network request 1234.5
|
|
chrome-use network har start
|
|
chrome-use network har stop ./capture.har
|
|
"##
|
|
}
|
|
|
|
// === Storage ===
|
|
"storage" => {
|
|
r##"
|
|
chrome-use storage - Manage web storage
|
|
|
|
Usage: chrome-use storage <type> [operation] [key] [value]
|
|
|
|
Manage localStorage and sessionStorage.
|
|
|
|
Types:
|
|
local localStorage
|
|
session sessionStorage
|
|
|
|
Operations:
|
|
get [key] Get all storage or specific key
|
|
set <key> <value> Set a key-value pair
|
|
clear Clear all storage
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use storage local
|
|
chrome-use storage local get authToken
|
|
chrome-use storage local set theme "dark"
|
|
chrome-use storage local clear
|
|
chrome-use storage session get userId
|
|
"##
|
|
}
|
|
|
|
// === Cookies ===
|
|
"cookies" => {
|
|
r##"
|
|
chrome-use cookies - Manage browser cookies
|
|
|
|
Usage: chrome-use cookies [operation] [args]
|
|
|
|
Manage browser cookies for the current context.
|
|
|
|
Operations:
|
|
get Get all cookies (default)
|
|
set <name> <value> [options] Set a cookie with optional properties
|
|
clear Clear all cookies
|
|
|
|
Cookie Set Options:
|
|
--url <url> URL for the cookie (allows setting before page load)
|
|
--domain <domain> Cookie domain (e.g., ".example.com")
|
|
--path <path> Cookie path (e.g., "/api")
|
|
--httpOnly Set HttpOnly flag (prevents JavaScript access)
|
|
--secure Set Secure flag (HTTPS only)
|
|
--sameSite <Strict|Lax|None> SameSite policy
|
|
--expires <timestamp> Expiration time (Unix timestamp in seconds)
|
|
|
|
Note: If --url, --domain, and --path are all omitted, the cookie will be set
|
|
for the current page URL.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
# Simple cookie for current page
|
|
chrome-use cookies set session_id "abc123"
|
|
|
|
# Set cookie for a URL before loading it (useful for authentication)
|
|
chrome-use cookies set session_id "abc123" --url https://app.example.com
|
|
|
|
# Set secure, httpOnly cookie with domain and path
|
|
chrome-use cookies set auth_token "xyz789" --domain example.com --path /api --httpOnly --secure
|
|
|
|
# Set cookie with SameSite policy
|
|
chrome-use cookies set tracking_consent "yes" --sameSite Strict
|
|
|
|
# Set cookie with expiration (Unix timestamp)
|
|
chrome-use cookies set temp_token "temp123" --expires 1735689600
|
|
|
|
# Get all cookies
|
|
chrome-use cookies
|
|
|
|
# Clear all cookies
|
|
chrome-use cookies clear
|
|
"##
|
|
}
|
|
|
|
// === Tabs ===
|
|
"tab" => {
|
|
r##"
|
|
chrome-use tab - Manage browser tabs
|
|
|
|
Usage: chrome-use tab [operation] [args]
|
|
|
|
Manage browser tabs in the current window. Stable tab ids look like `t1`,
|
|
`t2`, `t3`. An id is never reused within a session, so scripts can keep
|
|
referring to the same tab across commands. Optional user-assigned labels
|
|
(e.g. `docs`, `app`) are interchangeable with ids everywhere a tab ref is
|
|
accepted.
|
|
|
|
Operations:
|
|
list List open tabs with their ids and labels (default)
|
|
new [url] Open a new tab
|
|
new --label <name> [url] Open a new tab with a label like `docs` or `app`
|
|
close [t<N>|label] Close a tab (current if no ref given)
|
|
<t<N>|label> Switch to a tab by id or label
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use tab
|
|
chrome-use tab list
|
|
chrome-use tab new
|
|
chrome-use tab new https://example.com
|
|
chrome-use tab new --label docs https://docs.example.com
|
|
chrome-use tab t2
|
|
chrome-use tab docs
|
|
chrome-use tab close
|
|
chrome-use tab close t1
|
|
chrome-use tab close docs
|
|
"##
|
|
}
|
|
|
|
// === Window ===
|
|
"window" => {
|
|
r##"
|
|
chrome-use window - Manage browser windows
|
|
|
|
Usage: chrome-use window <operation>
|
|
|
|
Manage browser windows.
|
|
|
|
Operations:
|
|
new Open new browser window
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use window new
|
|
"##
|
|
}
|
|
|
|
// === Frame ===
|
|
"frame" => {
|
|
r##"
|
|
chrome-use frame - Switch frame context
|
|
|
|
Usage: chrome-use frame <selector|main>
|
|
|
|
Switch to an iframe or back to the main frame.
|
|
|
|
Arguments:
|
|
<selector> CSS selector for iframe
|
|
main Switch back to main frame
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use frame "#embed-iframe"
|
|
chrome-use frame "iframe[name='content']"
|
|
chrome-use frame main
|
|
"##
|
|
}
|
|
|
|
// === Auth ===
|
|
"auth" => {
|
|
r##"
|
|
chrome-use auth - Manage authentication profiles
|
|
|
|
Usage: chrome-use auth <subcommand> [args]
|
|
|
|
Subcommands:
|
|
save <name> Save credentials for a login profile
|
|
login <name> Login using saved credentials (waits for form fields)
|
|
list List saved profiles (names and URLs only)
|
|
show <name> Show profile metadata (no passwords)
|
|
delete <name> Delete a saved profile
|
|
|
|
Save Options:
|
|
--url <url> Login page URL (required)
|
|
--username <user> Username (required)
|
|
--password <pass> Password (required unless --password-stdin)
|
|
--password-stdin Read password from stdin (recommended)
|
|
--username-selector <s> Custom CSS selector for username field
|
|
--password-selector <s> Custom CSS selector for password field
|
|
--submit-selector <s> Custom CSS selector for submit button
|
|
|
|
Login behavior:
|
|
auth login waits for form selectors to appear before filling/clicking.
|
|
Selector wait timeout follows the default action timeout.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
echo "pass" | chrome-use auth save github --url https://github.com/login --username user --password-stdin
|
|
chrome-use auth save github --url https://github.com/login --username user --password pass
|
|
chrome-use auth login github
|
|
chrome-use auth list
|
|
chrome-use auth show github
|
|
chrome-use auth delete github
|
|
"##
|
|
}
|
|
|
|
// === Confirm/Deny ===
|
|
"confirm" | "deny" => {
|
|
r##"
|
|
chrome-use confirm/deny - Approve or deny pending actions
|
|
|
|
Usage:
|
|
chrome-use confirm <confirmation-id>
|
|
chrome-use deny <confirmation-id>
|
|
|
|
When --confirm-actions is set, certain action categories return a
|
|
confirmation_required response with a confirmation ID. Use confirm/deny
|
|
to approve or reject the action.
|
|
|
|
Pending confirmations auto-deny after 60 seconds.
|
|
|
|
Examples:
|
|
chrome-use confirm c_8f3a1234
|
|
chrome-use deny c_8f3a1234
|
|
"##
|
|
}
|
|
|
|
// === Dialog ===
|
|
"dialog" => {
|
|
r##"
|
|
chrome-use dialog - Handle browser dialogs
|
|
|
|
Usage: chrome-use dialog <accept|dismiss|status> [text]
|
|
|
|
Respond to or check for browser dialogs (alert, confirm, prompt).
|
|
|
|
Operations:
|
|
accept [text] Accept dialog, optionally with prompt text
|
|
dismiss Dismiss/cancel dialog
|
|
status Check if a dialog is currently open
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use dialog accept
|
|
chrome-use dialog accept "my input"
|
|
chrome-use dialog dismiss
|
|
chrome-use dialog status
|
|
"##
|
|
}
|
|
|
|
// === Trace ===
|
|
"trace" => {
|
|
r##"
|
|
chrome-use trace - Record execution trace
|
|
|
|
Usage: chrome-use trace <operation> [path]
|
|
|
|
Record a Chrome DevTools trace for debugging.
|
|
|
|
Operations:
|
|
start [path] Start recording trace
|
|
stop [path] Stop recording and save trace
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use trace start
|
|
chrome-use trace start ./my-trace
|
|
chrome-use trace stop
|
|
chrome-use trace stop ./debug-trace.zip
|
|
"##
|
|
}
|
|
|
|
// === Profile (CDP Tracing) ===
|
|
"profiler" => {
|
|
r##"
|
|
chrome-use profiler - Record Chrome DevTools performance profile
|
|
|
|
Usage: chrome-use profiler <operation> [options]
|
|
|
|
Record a performance profile using Chrome DevTools Protocol (CDP) Tracing.
|
|
The output JSON file can be loaded into Chrome DevTools Performance panel,
|
|
Perfetto UI (https://ui.perfetto.dev/), or other trace analysis tools.
|
|
|
|
Operations:
|
|
start Start profiling
|
|
stop [path] Stop profiling and save to file
|
|
|
|
Start Options:
|
|
--categories <list> Comma-separated trace categories (default includes
|
|
devtools.timeline, v8.execute, blink, and others)
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
# Basic profiling
|
|
chrome-use profiler start
|
|
chrome-use navigate https://example.com
|
|
chrome-use click "#button"
|
|
chrome-use profiler stop ./trace.json
|
|
|
|
# With custom categories
|
|
chrome-use profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
|
|
chrome-use profiler stop ./custom-trace.json
|
|
|
|
The output file can be viewed in:
|
|
- Chrome DevTools: Performance panel > Load profile
|
|
- Perfetto: https://ui.perfetto.dev/
|
|
"##
|
|
}
|
|
|
|
// === Record (video) ===
|
|
"record" => {
|
|
r##"
|
|
chrome-use record - Record browser session to video
|
|
|
|
Usage: chrome-use record start <path.webm> [url]
|
|
chrome-use record stop
|
|
chrome-use record restart <path.webm> [url]
|
|
|
|
Record the browser to a WebM video file.
|
|
Creates a fresh browser context but preserves cookies and localStorage.
|
|
If no URL is provided, automatically navigates to your current page.
|
|
|
|
Operations:
|
|
start <path> [url] Start recording (defaults to current URL if omitted)
|
|
stop Stop recording and save video
|
|
restart <path> [url] Stop current recording (if any) and start a new one
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
# Record from current page (preserves login state)
|
|
chrome-use open https://app.example.com/dashboard
|
|
chrome-use snapshot -i # Explore and plan
|
|
chrome-use record start ./demo.webm
|
|
chrome-use click @e3 # Execute planned actions
|
|
chrome-use record stop
|
|
|
|
# Or specify a different URL
|
|
chrome-use record start ./demo.webm https://example.com
|
|
|
|
# Restart recording with a new file (stops previous, starts new)
|
|
chrome-use record restart ./take2.webm
|
|
"##
|
|
}
|
|
|
|
// === Console/Errors ===
|
|
"console" => {
|
|
r##"
|
|
chrome-use console - View console logs
|
|
|
|
Usage: chrome-use console [--clear]
|
|
|
|
View browser console output (log, warn, error, info).
|
|
|
|
Options:
|
|
--clear Clear console log buffer
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use console
|
|
chrome-use console --clear
|
|
"##
|
|
}
|
|
"errors" => {
|
|
r##"
|
|
chrome-use errors - View page errors
|
|
|
|
Usage: chrome-use errors [--clear]
|
|
|
|
View JavaScript errors and uncaught exceptions.
|
|
|
|
Options:
|
|
--clear Clear error buffer
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use errors
|
|
chrome-use errors --clear
|
|
"##
|
|
}
|
|
|
|
// === Highlight ===
|
|
"highlight" => {
|
|
r##"
|
|
chrome-use highlight - Highlight an element
|
|
|
|
Usage: chrome-use highlight <selector>
|
|
|
|
Visually highlights an element on the page for debugging.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use highlight "#target-element"
|
|
chrome-use highlight @e5
|
|
"##
|
|
}
|
|
|
|
// === Clipboard ===
|
|
"clipboard" => {
|
|
r##"
|
|
chrome-use clipboard - Read and write clipboard
|
|
|
|
Usage: chrome-use clipboard <operation> [text]
|
|
|
|
Read from or write to the browser clipboard.
|
|
|
|
Operations:
|
|
read Read text from clipboard
|
|
write <text> Write text to clipboard
|
|
copy Copy current selection (simulates Ctrl+C)
|
|
paste Paste from clipboard (simulates Ctrl+V)
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use clipboard read
|
|
chrome-use clipboard write "Hello, World!"
|
|
chrome-use clipboard copy
|
|
chrome-use clipboard paste
|
|
"##
|
|
}
|
|
|
|
// === State ===
|
|
"state" => {
|
|
r##"
|
|
chrome-use state - Manage browser state
|
|
|
|
Usage: chrome-use state <operation> [args]
|
|
|
|
Save, restore, list, and manage browser state (cookies, localStorage, sessionStorage).
|
|
|
|
Operations:
|
|
save <path> Save current state to file
|
|
load <path> Load state from file
|
|
list List saved state files
|
|
show <filename> Show state summary
|
|
rename <old-name> <new-name> Rename state file
|
|
clear [session-name] [--all] Clear saved states
|
|
clean --older-than <days> Delete expired state files
|
|
|
|
Automatic State Persistence:
|
|
Use --session-name to auto-save/restore state across restarts:
|
|
chrome-use --session-name myapp open https://example.com
|
|
Or set AGENT_BROWSER_SESSION_NAME environment variable.
|
|
|
|
State Encryption:
|
|
Set AGENT_BROWSER_ENCRYPTION_KEY (64-char hex) for AES-256-GCM encryption.
|
|
Generate a key: openssl rand -hex 32
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use state save ./auth-state.json
|
|
chrome-use state load ./auth-state.json
|
|
chrome-use state list
|
|
chrome-use state show myapp-default.json
|
|
chrome-use state rename old-name new-name
|
|
chrome-use state clear --all
|
|
chrome-use state clean --older-than 7
|
|
"##
|
|
}
|
|
|
|
// === Session ===
|
|
"session" => {
|
|
r##"
|
|
chrome-use session - Manage sessions
|
|
|
|
Usage: chrome-use session [operation]
|
|
|
|
Manage isolated browser sessions. Each session has its own browser
|
|
instance with separate cookies, storage, and state.
|
|
|
|
Operations:
|
|
(none) Show current session name
|
|
list List all active sessions
|
|
|
|
Environment:
|
|
AGENT_BROWSER_SESSION Default session name
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use session
|
|
chrome-use session list
|
|
chrome-use --session test open example.com
|
|
"##
|
|
}
|
|
|
|
// === Install ===
|
|
"install" => {
|
|
r##"
|
|
chrome-use install - Install browser binaries
|
|
|
|
Usage: chrome-use install [--with-deps]
|
|
|
|
Downloads and installs browser binaries required for automation.
|
|
|
|
Options:
|
|
-d, --with-deps Also install system dependencies (Linux only)
|
|
|
|
Examples:
|
|
chrome-use install
|
|
chrome-use install --with-deps
|
|
"##
|
|
}
|
|
|
|
// === Upgrade ===
|
|
"upgrade" => {
|
|
r##"
|
|
chrome-use upgrade - Upgrade to the latest version
|
|
|
|
Usage: chrome-use upgrade
|
|
|
|
Detects the current installation method (npm, Homebrew, or Cargo) and runs
|
|
the appropriate update command. Displays the version change on success, or
|
|
informs you if you are already on the latest version.
|
|
|
|
Examples:
|
|
chrome-use upgrade
|
|
"##
|
|
}
|
|
|
|
// === Doctor ===
|
|
"doctor" => {
|
|
r##"
|
|
chrome-use doctor - Diagnose and repair your install
|
|
|
|
Usage: chrome-use doctor [options]
|
|
|
|
Runs a battery of checks across environment, Chrome install, daemon state,
|
|
config files, encryption key, providers, network reachability, and a live
|
|
headless browser launch test.
|
|
|
|
Auto-cleans stale daemon socket/pid/version sidecar files. Destructive
|
|
repairs (reinstalling Chrome, purging old state files, generating a missing
|
|
encryption key) are gated behind --fix.
|
|
|
|
Options:
|
|
--offline Skip network probes
|
|
--quick Skip the live headless launch test
|
|
--fix Also run destructive repairs
|
|
--json JSON output
|
|
|
|
Exit codes:
|
|
0 All checks pass (warnings OK)
|
|
1 At least one check failed
|
|
|
|
Examples:
|
|
chrome-use doctor
|
|
chrome-use doctor --offline --quick
|
|
chrome-use doctor --fix
|
|
chrome-use doctor --json
|
|
"##
|
|
}
|
|
|
|
// === Dashboard ===
|
|
"dashboard" => {
|
|
r##"
|
|
chrome-use dashboard - Observability dashboard
|
|
|
|
Usage: chrome-use dashboard [start|stop] [options]
|
|
|
|
Manage the observability dashboard, a local web UI that shows live
|
|
browser viewports and command activity feeds for all sessions.
|
|
The dashboard is bundled into the binary and requires no separate install.
|
|
|
|
Subcommands:
|
|
start [--port <n>] Start the dashboard server (default port: 4848)
|
|
stop Stop the dashboard server
|
|
|
|
Running 'chrome-use dashboard' with no subcommand is equivalent to 'dashboard start'.
|
|
|
|
The dashboard runs as a standalone background process, independent of
|
|
browser sessions. All sessions automatically stream to the dashboard.
|
|
It works from http://localhost:4848 or a proxied/forwarded URL that
|
|
reaches the dashboard server, such as https://dashboard.chrome-use.localhost
|
|
or a Coder workspace URL. The browser stays on the dashboard origin;
|
|
session tabs, status, and stream traffic are proxied internally, so
|
|
session ports do not need to be exposed.
|
|
|
|
Options:
|
|
--port <n> Port for the dashboard server (default: 4848)
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
|
|
Examples:
|
|
chrome-use dashboard start
|
|
chrome-use dashboard start --port 8080
|
|
chrome-use dashboard stop
|
|
"##
|
|
}
|
|
|
|
// === Connect ===
|
|
"connect" => {
|
|
r##"
|
|
chrome-use connect - Connect to browser via CDP
|
|
|
|
Usage: chrome-use connect <port|url>
|
|
|
|
Connects to a running browser instance via Chrome DevTools Protocol (CDP).
|
|
This allows controlling browsers, Electron apps, or remote browser services.
|
|
|
|
Arguments:
|
|
<port> Local port number (e.g., 9222)
|
|
<url> Full WebSocket URL (ws://, wss://, http://, https://)
|
|
|
|
Supported URL formats:
|
|
- Port number: 9222 (connects to http://localhost:9222)
|
|
- WebSocket URL: ws://localhost:9222/devtools/browser/...
|
|
- Remote service: wss://remote-browser.example.com/cdp?token=...
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
# Connect to local Chrome with remote debugging
|
|
# Start Chrome: google-chrome --remote-debugging-port=9222
|
|
chrome-use connect 9222
|
|
|
|
# Connect using WebSocket URL from /json/version endpoint
|
|
chrome-use connect "ws://localhost:9222/devtools/browser/abc123"
|
|
|
|
# Connect to remote browser service
|
|
chrome-use connect "wss://browser-service.example.com/cdp?token=xyz"
|
|
|
|
# After connecting, run commands normally
|
|
chrome-use snapshot
|
|
chrome-use click @e1
|
|
"##
|
|
}
|
|
|
|
// === Runtime streaming ===
|
|
"stream" => {
|
|
r##"
|
|
chrome-use stream - Manage live WebSocket browser streaming
|
|
|
|
Usage:
|
|
chrome-use stream enable [--port <port>]
|
|
chrome-use stream disable
|
|
chrome-use stream status
|
|
|
|
Enables or disables the session-scoped WebSocket stream server without restarting
|
|
an already-running daemon. If --port is omitted, chrome-use binds an
|
|
available localhost port automatically and reports it back.
|
|
|
|
Notes:
|
|
- 'stream enable' creates the WebSocket server.
|
|
- WebSocket clients trigger frame streaming automatically.
|
|
- 'screencast_start' and 'screencast_stop' still control explicit CDP screencasts.
|
|
- Streaming is always enabled. Set AGENT_BROWSER_STREAM_PORT to bind to a
|
|
specific port instead of the default OS-assigned port.
|
|
|
|
The WS is BIDIRECTIONAL — the high-throughput way to drive a live/real-time page
|
|
(games, canvas apps) instead of one screenshot + one CLI call per action:
|
|
- Server -> client (JSON text frames):
|
|
{"type":"frame","data":"<base64 jpeg>"} live screencast (~60fps)
|
|
plus status / tabs messages.
|
|
- Client -> server (send JSON text):
|
|
{"type":"input_keyboard","eventType":"keyDown|keyUp","key":" ","code":"Space",
|
|
"windowsVirtualKeyCode":32}
|
|
{"type":"input_mouse","eventType":"mousePressed|mouseReleased|mouseMoved",
|
|
"x":640,"y":360,"button":"left","clickCount":1}
|
|
{"type":"input_touch","eventType":"touchStart|touchEnd","touchPoints":[...]}
|
|
Connect once and run a tight local loop: read frames, send timed input — no
|
|
per-action process spawn, no round-trip. Works over the extension relay too.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use stream status
|
|
chrome-use stream enable
|
|
chrome-use stream enable --port 9223
|
|
chrome-use stream disable
|
|
"##
|
|
}
|
|
|
|
// === iOS Commands ===
|
|
"tap" => {
|
|
r##"
|
|
chrome-use tap - Tap an element (touch gesture)
|
|
|
|
Usage: chrome-use tap <selector>
|
|
|
|
Taps an element. This is an alias for 'click' that provides semantic clarity
|
|
for touch-based interfaces like iOS Safari.
|
|
|
|
Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use tap "#submit-button"
|
|
chrome-use tap @e1
|
|
chrome-use -p ios tap "button:has-text('Sign In')"
|
|
"##
|
|
}
|
|
"swipe" => {
|
|
r##"
|
|
chrome-use swipe - Swipe gesture (iOS)
|
|
|
|
Usage: chrome-use swipe <direction> [distance]
|
|
|
|
Performs a swipe gesture on iOS Safari. The direction determines
|
|
which way the content moves (swipe up scrolls down, etc.).
|
|
|
|
Arguments:
|
|
direction up, down, left, or right
|
|
distance Optional distance in pixels (default: 300)
|
|
|
|
Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use -p ios swipe up
|
|
chrome-use -p ios swipe down 500
|
|
chrome-use -p ios swipe left
|
|
"##
|
|
}
|
|
"device" => {
|
|
r##"
|
|
chrome-use device - Manage iOS simulators
|
|
|
|
Usage: chrome-use device <subcommand>
|
|
|
|
Subcommands:
|
|
list List available iOS simulators
|
|
|
|
Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use device list
|
|
chrome-use -p ios device list
|
|
"##
|
|
}
|
|
|
|
"diff" => {
|
|
r##"
|
|
chrome-use diff - Compare page states
|
|
|
|
Subcommands:
|
|
|
|
diff snapshot Compare current snapshot to last snapshot in session
|
|
diff screenshot --baseline <f> Visual pixel diff against a baseline image
|
|
diff url <url1> <url2> Compare two pages
|
|
|
|
Snapshot Diff:
|
|
|
|
Usage: chrome-use diff snapshot [options]
|
|
|
|
Options:
|
|
-b, --baseline <file> Compare against a saved snapshot file
|
|
-s, --selector <sel> Scope snapshot to a CSS selector or @ref
|
|
-c, --compact Use compact snapshot format
|
|
-d, --depth <n> Limit snapshot tree depth
|
|
|
|
Without --baseline, compares against the last snapshot taken in this session.
|
|
|
|
Screenshot Diff:
|
|
|
|
Usage: chrome-use diff screenshot --baseline <file> [options]
|
|
|
|
Options:
|
|
-b, --baseline <file> Baseline image to compare against (required)
|
|
-o, --output <file> Path for the diff image (default: temp dir)
|
|
-t, --threshold <0-1> Color distance threshold (default: 0.1)
|
|
-s, --selector <sel> Scope screenshot to element
|
|
--full Full page screenshot
|
|
|
|
URL Diff:
|
|
|
|
Usage: chrome-use diff url <url1> <url2> [options]
|
|
|
|
Options:
|
|
--screenshot Also compare screenshots (default: snapshot only)
|
|
--full Full page screenshots
|
|
--wait-until <strategy> Navigation wait strategy: load, domcontentloaded, networkidle (default: load)
|
|
-s, --selector <sel> Scope snapshots to a CSS selector or @ref
|
|
-c, --compact Use compact snapshot format
|
|
-d, --depth <n> Limit snapshot tree depth
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
--session <name> Use specific session
|
|
|
|
Examples:
|
|
chrome-use diff snapshot
|
|
chrome-use diff snapshot --baseline before.txt
|
|
chrome-use diff screenshot --baseline before.png
|
|
chrome-use diff screenshot --baseline before.png --output diff.png --threshold 0.2
|
|
chrome-use diff url https://staging.example.com https://prod.example.com
|
|
chrome-use diff url https://v1.example.com https://v2.example.com --screenshot
|
|
"##
|
|
}
|
|
|
|
"batch" => {
|
|
r##"
|
|
chrome-use batch - Execute multiple commands sequentially
|
|
|
|
Usage: chrome-use batch [options] "<cmd1>" "<cmd2>" ...
|
|
echo '<json>' | chrome-use batch [options]
|
|
|
|
Runs multiple commands in sequence. Commands can be passed as quoted
|
|
arguments or piped as JSON via stdin. Results are printed in order,
|
|
separated by blank lines (or as a JSON array with --json).
|
|
|
|
Options:
|
|
--bail Stop on first error (default: continue all commands)
|
|
--json Output results as a JSON array
|
|
|
|
Argument Mode:
|
|
Each quoted argument is a full command string:
|
|
chrome-use batch "open https://example.com" "snapshot -i" "screenshot"
|
|
|
|
Stdin Mode (JSON):
|
|
A JSON array of string arrays. Each inner array is one command:
|
|
[
|
|
["open", "https://example.com"],
|
|
["snapshot", "-i"],
|
|
["click", "@e1"],
|
|
["fill", "@e2", "test@example.com"],
|
|
["screenshot", "result.png"]
|
|
]
|
|
|
|
Examples:
|
|
chrome-use batch "open https://example.com" "screenshot"
|
|
chrome-use batch --bail "open https://example.com" "click @e1" "screenshot"
|
|
echo '[["open", "https://example.com"], ["snapshot"]]' | chrome-use batch
|
|
chrome-use batch --bail < commands.json
|
|
"##
|
|
}
|
|
|
|
"profiles" => {
|
|
r##"
|
|
chrome-use profiles - List available Chrome profiles
|
|
|
|
Usage: chrome-use profiles
|
|
|
|
Lists all Chrome profiles found in your Chrome user data directory, showing
|
|
the directory name and display name for each profile. Use the directory name
|
|
with --profile to launch Chrome with that profile's login state.
|
|
|
|
Global Options:
|
|
--json Output as JSON
|
|
|
|
Examples:
|
|
chrome-use profiles
|
|
chrome-use profiles --json
|
|
chrome-use --profile Default open https://gmail.com
|
|
"##
|
|
}
|
|
|
|
"chat" => {
|
|
r##"
|
|
chrome-use chat - Natural language browser control via AI
|
|
|
|
Usage:
|
|
chrome-use chat <message> Single-shot: execute instruction and exit
|
|
chrome-use chat Interactive REPL (when stdin is a TTY)
|
|
echo "instruction" | chrome-use chat Piped input
|
|
|
|
Sends natural language instructions to an AI model that translates them
|
|
into chrome-use commands and executes them against the active session.
|
|
Requires AI_GATEWAY_API_KEY to be set.
|
|
|
|
In interactive mode, type "quit", "exit", or "q" to leave the REPL.
|
|
|
|
Chat Options:
|
|
--model <name> AI model (or AI_GATEWAY_MODEL env, default: anthropic/claude-sonnet-4.6)
|
|
-v, --verbose Show tool commands and their raw output
|
|
-q, --quiet Show only the AI text response (hide tool calls)
|
|
|
|
Global Options:
|
|
--json Structured JSON output per turn
|
|
--session <name> Target session for commands
|
|
|
|
Examples:
|
|
chrome-use chat "open google.com and search for cats"
|
|
chrome-use chat "take a screenshot of the current page"
|
|
chrome-use -q chat "summarize this page"
|
|
chrome-use -v chat "fill in the login form with test@example.com"
|
|
chrome-use --model openai/gpt-4o chat "navigate to hacker news"
|
|
chrome-use chat
|
|
"##
|
|
}
|
|
|
|
"skills" => {
|
|
r##"
|
|
chrome-use skills - List and retrieve bundled skill content
|
|
|
|
Usage: chrome-use skills [subcommand] [options]
|
|
|
|
Subcommands:
|
|
list List all available skills (default)
|
|
get <name> [name...] Output a skill's full content
|
|
get <name> --full Include references and templates
|
|
get --all Output every skill
|
|
path [name] Print filesystem path to skill directory
|
|
|
|
Options:
|
|
--json Output as JSON
|
|
|
|
The skills command serves bundled skill content that always matches the
|
|
installed CLI version. Agents should use this to get current instructions
|
|
rather than relying on cached copies.
|
|
|
|
Examples:
|
|
chrome-use skills
|
|
chrome-use skills list
|
|
chrome-use skills get core
|
|
chrome-use skills get core --full
|
|
chrome-use skills get electron --full
|
|
chrome-use skills get --all
|
|
chrome-use skills path core
|
|
chrome-use skills list --json
|
|
|
|
Environment:
|
|
AGENT_BROWSER_SKILLS_DIR Override the skills directory path
|
|
"##
|
|
}
|
|
|
|
_ => return false,
|
|
};
|
|
println!("{}", help.trim());
|
|
true
|
|
}
|
|
|
|
pub fn print_help() {
|
|
println!(
|
|
r#"
|
|
chrome-use - fast browser automation CLI for AI agents
|
|
|
|
Usage: chrome-use <command> [args] [options]
|
|
|
|
Start here (for AI agents):
|
|
chrome-use skills get core --full
|
|
|
|
Skills ship with the CLI (always version-matched) and include workflow
|
|
patterns, ref/selector usage, and copy-paste examples. Prefer this over
|
|
guessing commands from flag docs alone. Specialized skills cover Electron
|
|
apps, Slack, exploratory testing, and cloud browser providers.
|
|
|
|
skills [list] List available skills
|
|
skills get core Core usage guide (overview + common patterns)
|
|
skills get core --full Include full command reference and templates
|
|
skills get <name> Load a specialized skill (electron, slack, ...)
|
|
skills path [name] Print skill directory path
|
|
|
|
Core Commands:
|
|
open <url> Navigate to URL
|
|
click <sel|x y> Click element/@ref, or a viewport coordinate
|
|
dblclick <sel> Double-click element
|
|
type <sel> <text> Type into element
|
|
fill <sel> <text> Clear and fill
|
|
press <key> [--hold <ms>] Press key (Enter, Tab, Control+a). --hold keeps it
|
|
down <ms> then releases — precise (in-daemon), for
|
|
games/charge: `press d --hold 800`
|
|
keydown <key> Hold a key down (no auto-release) — for games/shortcuts
|
|
keyup <key> Release a held key. Pair with keydown to hold-to-move:
|
|
`keydown d` … `keyup d`
|
|
keyboard type <text> Type text with real keystrokes (no selector)
|
|
keyboard inserttext <text> Insert text without key events
|
|
hover <sel> Hover element
|
|
focus <sel> Focus element
|
|
check <sel> Check checkbox
|
|
uncheck <sel> Uncheck checkbox
|
|
select <sel> <val...> Select dropdown option
|
|
drag <src> <dst> Drag and drop
|
|
upload <sel> <files...> Upload files
|
|
download <sel> <path> Download file by clicking element
|
|
scroll <dir> [px] Scroll (up/down/left/right)
|
|
scrollintoview <sel> Scroll element into view
|
|
wait <sel|ms> Wait for element or time
|
|
screenshot [path] Take screenshot
|
|
pdf <path> Save as PDF
|
|
snapshot Accessibility tree with refs (for AI)
|
|
eval <js> Run JavaScript
|
|
connect <port|url> Connect to browser via CDP
|
|
close [--all] Close browser (--all closes every session)
|
|
|
|
Navigation:
|
|
back Go back
|
|
forward Go forward
|
|
reload Reload page
|
|
|
|
Get Info: chrome-use get <what> [selector]
|
|
text, html, value, attr <name>, title, url, count, box, styles, cdp-url
|
|
text (no selector = whole page, all frames), text --main, frames (list)
|
|
|
|
Check State: chrome-use is <what> <selector>
|
|
visible, enabled, checked
|
|
|
|
Anti-bot: chrome-use stealth | cf-status
|
|
stealth stealth self-check (webdriver/UA/plugins + overrides)
|
|
cf-status Cloudflare challenge + cf_clearance preflight (skip re-solving)
|
|
|
|
Find Elements: chrome-use find <locator> <value> <action> [text]
|
|
role, text, label, placeholder, alt, title, testid, first, last, nth
|
|
|
|
Mouse: chrome-use mouse <action> [args]
|
|
move <x> <y>, down [btn], up [btn], wheel <dy> [dx]
|
|
|
|
Browser Settings: chrome-use set <setting> [value]
|
|
viewport <w> <h>, device <name>, geo <lat> <lng>
|
|
offline [on|off], headers <json>, credentials <user> <pass>
|
|
media [dark|light] [reduced-motion]
|
|
|
|
Network: chrome-use network <action>
|
|
route <url> [--abort|--body <json>] [--resource-type <csv>]
|
|
unroute [url]
|
|
requests [--clear] [--filter <pattern>]
|
|
har <start|stop> [path]
|
|
|
|
Storage:
|
|
cookies [get|set|clear] Manage cookies (set supports --url, --domain, --path, --httpOnly, --secure, --sameSite, --expires)
|
|
Or: cookies set --curl <file> [--domain <host>] (auto-detects JSON/cURL/Cookie-header files)
|
|
cookies export --from <profile> [--domain <d>[,<d>]]
|
|
Decrypt another Chrome profile's cookies -> JSON for `cookies set --curl` (macOS)
|
|
cookies transfer --from <profile> [--domain <d>[,<d>]]
|
|
Copy a logged-in session from another profile into the connected browser (macOS)
|
|
storage <local|session> Manage web storage
|
|
|
|
Tabs:
|
|
tab [new|list|close|<ref>] Manage tabs (<ref> = t<N>, a label, or a CDP targetId)
|
|
tab list --full Full URLs + stable cross-session targetId per tab
|
|
tab <targetId> Adopt a specific tab (incl. another session's) by its
|
|
stable targetId, no reload — preserves in-page state
|
|
open <url> --reuse-tab Reuse an existing tab on that URL instead of spawning
|
|
a duplicate (matches origin+path; preserves state)
|
|
|
|
Diff:
|
|
diff snapshot Compare current vs last snapshot
|
|
diff screenshot --baseline Compare current vs baseline image
|
|
diff url <u1> <u2> Compare two pages
|
|
|
|
Debug:
|
|
trace start|stop [path] Record Chrome DevTools trace
|
|
profiler start|stop [path] Record Chrome DevTools profile
|
|
record start <path> [url] Start video recording (WebM)
|
|
record stop Stop and save video
|
|
console [--clear] View console logs
|
|
errors [--clear] View page errors
|
|
highlight <sel> Highlight element
|
|
inspect Open Chrome DevTools for the active page
|
|
clipboard <op> [text] Read/write clipboard (read, write, copy, paste)
|
|
|
|
Streaming:
|
|
stream enable [--port <n>] Start runtime WebSocket streaming for this session
|
|
stream disable Stop runtime WebSocket streaming
|
|
stream status Show streaming status and active port
|
|
|
|
React (requires `open --enable react-devtools`):
|
|
react tree Full React component tree (depth id parent name columns)
|
|
react inspect <id> Inspect one fiber (props, hooks, state, source)
|
|
react renders start Start recording re-renders via onCommitFiberRoot
|
|
react renders stop [--json] Stop and print render profile
|
|
react suspense [--only-dynamic] [--json]
|
|
Walk Suspense boundaries + classifier report
|
|
--only-dynamic hides the "static" list
|
|
|
|
Performance:
|
|
vitals [url] [--json] Core Web Vitals (LCP/CLS/TTFB/FCP/INP) +
|
|
React hydration timing when profiling build detected
|
|
|
|
SPA:
|
|
pushstate <url> SPA client-side nav. Auto-detects window.next.router.push
|
|
(triggers RSC fetch on Next.js); falls back to
|
|
history.pushState + popstate/navigate events for other frameworks
|
|
|
|
Init scripts:
|
|
removeinitscript <id> Remove a script registered via --init-script or addinitscript
|
|
|
|
Batch:
|
|
batch [--bail] ["cmd" ...] Execute multiple commands sequentially (args or stdin)
|
|
--bail stops on first error (default: continue all)
|
|
|
|
Auth Vault:
|
|
auth save <name> [opts] Save auth profile (--url, --username, --password/--password-stdin)
|
|
auth login <name> Login using saved credentials (waits for form fields)
|
|
auth list List saved auth profiles
|
|
auth show <name> Show auth profile metadata
|
|
auth delete <name> Delete auth profile
|
|
|
|
Confirmation:
|
|
confirm <id> Approve a pending action
|
|
deny <id> Deny a pending action
|
|
|
|
Sessions:
|
|
session Show current session name
|
|
session list List active sessions
|
|
sessions List running session daemons (alias of daemon status)
|
|
daemon status List running session daemons (+ relay state)
|
|
daemon restart Kill all session daemons; keeps the extension relay
|
|
up. Clears stale/cross-leaked state after an upgrade.
|
|
|
|
Chat (AI):
|
|
chat <message> Send a natural language instruction (single-shot)
|
|
chat Start interactive chat (REPL mode when stdin is a TTY)
|
|
Options: --model <name>, -v/--verbose, -q/--quiet
|
|
|
|
Dashboard:
|
|
dashboard [start] Start the dashboard server (default port: 4848)
|
|
dashboard start --port <n> Start on a specific port
|
|
dashboard stop Stop the dashboard server
|
|
|
|
Setup:
|
|
install Install browser binaries
|
|
install --with-deps Also install system dependencies (Linux)
|
|
upgrade Upgrade to the latest version
|
|
doctor [--fix] Diagnose install; auto-clean stale files
|
|
dashboard start Start the observability dashboard
|
|
profiles List available Chrome profiles
|
|
|
|
Snapshot Options:
|
|
-i, --interactive Only interactive elements
|
|
-c, --compact Remove empty structural elements
|
|
-d, --depth <n> Limit tree depth
|
|
-s, --selector <sel> Scope to CSS selector
|
|
|
|
Authentication:
|
|
--profile <name|path> Chrome profile name (e.g., Default) to reuse login state,
|
|
or a directory path for a persistent custom profile
|
|
(or AGENT_BROWSER_PROFILE env)
|
|
--session-name <name> Auto-save/restore cookies and localStorage by name
|
|
(or AGENT_BROWSER_SESSION_NAME env)
|
|
--state <path> Load saved auth state (cookies + storage) from JSON file
|
|
(or AGENT_BROWSER_STATE env)
|
|
--auto-connect Connect to a running Chrome (DEFAULT - shares cookies/sessions)
|
|
Tip: enable CDP via chrome://inspect/#remote-debugging
|
|
--launch, --new Launch a fresh browser instead of connecting to existing
|
|
--headers <json> HTTP headers scoped to URL's origin (e.g., Authorization bearer token)
|
|
|
|
Options:
|
|
--session <name> Isolated session (or AGENT_BROWSER_SESSION env)
|
|
--executable-path <path> Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH)
|
|
--extension <path> Load browser extensions (repeatable)
|
|
--init-script <path> Register a page init script before the first navigation (repeatable)
|
|
(or AGENT_BROWSER_INIT_SCRIPTS env, comma-separated)
|
|
--enable <feature> Built-in init scripts: react-devtools (repeatable or comma-separated)
|
|
(or AGENT_BROWSER_ENABLE env)
|
|
--args <args> Browser launch args, comma or newline separated (or AGENT_BROWSER_ARGS)
|
|
e.g., --args "--no-sandbox,--disable-blink-features=AutomationControlled"
|
|
--user-agent <ua> Custom User-Agent (or AGENT_BROWSER_USER_AGENT)
|
|
--proxy <server> Proxy server URL (or AGENT_BROWSER_PROXY, HTTP_PROXY, HTTPS_PROXY, ALL_PROXY)
|
|
Supports authenticated proxies: --proxy "http://user:pass@127.0.0.1:7890"
|
|
--proxy-bypass <hosts> Bypass proxy for these hosts (or AGENT_BROWSER_PROXY_BYPASS, NO_PROXY)
|
|
e.g., --proxy-bypass "localhost,*.internal.com"
|
|
--ignore-https-errors Ignore HTTPS certificate errors
|
|
--allow-file-access Allow file:// URLs to access local files (Chromium only)
|
|
--hide-scrollbars <bool> Hide native scrollbars in headless Chromium screenshots (default: true)
|
|
Use --hide-scrollbars false to keep scrollbars visible
|
|
-p, --provider <name> Browser provider: ios, browserbase, kernel, browseruse, browserless, agentcore
|
|
--device <name> iOS device name (e.g., "iPhone 15 Pro")
|
|
--json JSON output
|
|
--annotate Annotated screenshot with numbered labels and legend
|
|
--screenshot-dir <path> Default screenshot output directory (or AGENT_BROWSER_SCREENSHOT_DIR)
|
|
--screenshot-quality <n> JPEG quality 0-100; ignored for PNG (or AGENT_BROWSER_SCREENSHOT_QUALITY)
|
|
--screenshot-format <fmt> Screenshot format: png, jpeg (or AGENT_BROWSER_SCREENSHOT_FORMAT)
|
|
--headed Always on (default). Headless is forbidden (bot-detection tell);
|
|
display-less servers can opt back in with AGENT_BROWSER_ALLOW_HEADLESS=1
|
|
--cdp <port> Connect via CDP (Chrome DevTools Protocol)
|
|
--color-scheme <scheme> Color scheme: dark, light, no-preference (or AGENT_BROWSER_COLOR_SCHEME)
|
|
--download-path <path> Default download directory (or AGENT_BROWSER_DOWNLOAD_PATH)
|
|
--content-boundaries Wrap page output in boundary markers (or AGENT_BROWSER_CONTENT_BOUNDARIES)
|
|
--max-output <chars> Truncate page output to N chars (or AGENT_BROWSER_MAX_OUTPUT)
|
|
--allowed-domains <list> Restrict navigation domains (or AGENT_BROWSER_ALLOWED_DOMAINS)
|
|
--action-policy <path> Action policy JSON file (or AGENT_BROWSER_ACTION_POLICY)
|
|
--confirm-actions <list> Categories requiring confirmation (or AGENT_BROWSER_CONFIRM_ACTIONS)
|
|
--confirm-interactive Interactive confirmation prompts; auto-denies if stdin is not a TTY (or AGENT_BROWSER_CONFIRM_INTERACTIVE)
|
|
--engine <name> Browser engine: chrome (default), lightpanda (or AGENT_BROWSER_ENGINE)
|
|
--no-auto-dialog Disable automatic dismissal of alert/beforeunload dialogs (or AGENT_BROWSER_NO_AUTO_DIALOG)
|
|
--model <name> AI model for chat (or AI_GATEWAY_MODEL env)
|
|
-v, --verbose Show tool commands and their raw output
|
|
-q, --quiet Show only AI text responses (hide tool calls)
|
|
--config <path> Use a custom config file (or AGENT_BROWSER_CONFIG env)
|
|
--debug Debug output
|
|
--version, -V Show version
|
|
|
|
Configuration:
|
|
chrome-use looks for chrome-use.json in these locations (lowest to highest priority):
|
|
1. ~/.chrome-use/config.json User-level defaults
|
|
2. ./chrome-use.json Project-level overrides
|
|
3. Environment variables Override config file values
|
|
4. CLI flags Override everything
|
|
|
|
Use --config <path> to load a specific config file instead of the defaults.
|
|
If --config points to a missing or invalid file, chrome-use exits with an error.
|
|
|
|
Boolean flags accept an optional true/false value to override config:
|
|
--headed (same as --headed true)
|
|
--headed false (disables "headed": true from config)
|
|
--hide-scrollbars false (keeps native scrollbars visible in headless Chromium screenshots)
|
|
|
|
Extensions from user and project configs are merged (not replaced).
|
|
|
|
Example chrome-use.json:
|
|
{{"headed": true, "hideScrollbars": false, "proxy": "http://localhost:8080"}}
|
|
|
|
Environment:
|
|
AGENT_BROWSER_CONFIG Path to config file (or use --config)
|
|
AGENT_BROWSER_SESSION Session name (default: "default")
|
|
AGENT_BROWSER_SESSION_NAME Auto-save/restore state persistence name
|
|
AGENT_BROWSER_ENCRYPTION_KEY 64-char hex key for AES-256-GCM state encryption
|
|
AGENT_BROWSER_STATE_EXPIRE_DAYS Auto-delete states older than N days (default: 30)
|
|
AGENT_BROWSER_EXECUTABLE_PATH Custom browser executable path
|
|
AGENT_BROWSER_EXTENSIONS Comma-separated browser extension paths
|
|
AGENT_BROWSER_INIT_SCRIPTS Comma-separated paths to page init scripts
|
|
AGENT_BROWSER_ENABLE Comma-separated built-in init script features (e.g. react-devtools)
|
|
AGENT_BROWSER_HEADED Show browser window (not headless)
|
|
AGENT_BROWSER_JSON JSON output
|
|
AGENT_BROWSER_ANNOTATE Annotated screenshot with numbered labels and legend
|
|
AGENT_BROWSER_DEBUG Debug output
|
|
AGENT_BROWSER_IGNORE_HTTPS_ERRORS Ignore HTTPS certificate errors
|
|
AGENT_BROWSER_PROVIDER Browser provider (ios, browserbase, kernel, browseruse, browserless, agentcore)
|
|
AGENT_BROWSER_AUTO_CONNECT Auto-discover and connect to running Chrome
|
|
AGENT_BROWSER_ALLOW_FILE_ACCESS Allow file:// URLs to access local files
|
|
AGENT_BROWSER_HIDE_SCROLLBARS Hide scrollbars in headless Chromium screenshots (default: true)
|
|
AGENT_BROWSER_COLOR_SCHEME Color scheme preference (dark, light, no-preference)
|
|
AGENT_BROWSER_DOWNLOAD_PATH Default download directory for browser downloads
|
|
AGENT_BROWSER_DEFAULT_TIMEOUT Default action timeout in ms (default: 25000)
|
|
AGENT_BROWSER_SESSION_NAME Auto-save/load state persistence name
|
|
AGENT_BROWSER_STATE_EXPIRE_DAYS Auto-delete saved states older than N days (default: 30)
|
|
AGENT_BROWSER_ENCRYPTION_KEY 64-char hex key for AES-256-GCM session encryption
|
|
AGENT_BROWSER_STREAM_PORT Override WebSocket streaming port (default: OS-assigned)
|
|
AGENT_BROWSER_IDLE_TIMEOUT_MS Auto-shutdown daemon after N ms of inactivity (disabled by default)
|
|
AGENT_BROWSER_IOS_DEVICE Default iOS device name
|
|
AGENT_BROWSER_IOS_UDID Default iOS device UDID
|
|
AGENT_BROWSER_CONTENT_BOUNDARIES Wrap page output in boundary markers
|
|
AGENT_BROWSER_MAX_OUTPUT Max characters for page output
|
|
AGENT_BROWSER_ALLOWED_DOMAINS Comma-separated allowed domain patterns
|
|
AGENT_BROWSER_ACTION_POLICY Path to action policy JSON file
|
|
AGENT_BROWSER_CONFIRM_ACTIONS Action categories requiring confirmation
|
|
AGENT_BROWSER_CONFIRM_INTERACTIVE Enable interactive confirmation prompts
|
|
AGENT_BROWSER_NO_AUTO_DIALOG Disable automatic dismissal of alert/beforeunload dialogs
|
|
AGENT_BROWSER_ENGINE Browser engine: chrome (default), lightpanda
|
|
HTTP_PROXY / HTTPS_PROXY Standard proxy env vars (fallback if AGENT_BROWSER_PROXY not set)
|
|
ALL_PROXY SOCKS proxy (fallback for proxy)
|
|
NO_PROXY Bypass proxy for hosts (fallback for proxy-bypass)
|
|
AGENT_BROWSER_SCREENSHOT_DIR Default screenshot output directory
|
|
AGENT_BROWSER_SCREENSHOT_QUALITY JPEG quality 0-100
|
|
AGENT_BROWSER_SCREENSHOT_FORMAT Screenshot format: png, jpeg
|
|
AI_GATEWAY_URL Vercel AI Gateway base URL (default: https://ai-gateway.vercel.sh)
|
|
AI_GATEWAY_API_KEY API key for the AI Gateway (enables chat command and dashboard AI chat)
|
|
AI_GATEWAY_MODEL Default AI model (default: anthropic/claude-sonnet-4.6, or --model flag)
|
|
|
|
Install:
|
|
npm install -g chrome-use # npm
|
|
brew install chrome-use # Homebrew
|
|
cargo install chrome-use # Cargo
|
|
chrome-use install # Download Chrome (first time)
|
|
|
|
Examples:
|
|
chrome-use open example.com
|
|
chrome-use snapshot -i # Interactive elements only
|
|
chrome-use click @e2 # Click by ref from snapshot
|
|
chrome-use fill @e3 "test@example.com"
|
|
chrome-use find role button click --name Submit
|
|
chrome-use get text @e1
|
|
chrome-use screenshot --full
|
|
chrome-use screenshot --annotate # Labeled screenshot for vision models
|
|
chrome-use wait 2000 # Wait for slow pages to settle
|
|
chrome-use --cdp 9222 snapshot # Connect via CDP port
|
|
chrome-use --auto-connect snapshot # Auto-discover running Chrome
|
|
chrome-use stream enable # Start runtime streaming on an auto-selected port
|
|
chrome-use stream status # Inspect runtime streaming state
|
|
chrome-use --color-scheme dark open example.com # Dark mode
|
|
chrome-use --profile Default open gmail.com # Reuse Chrome login state
|
|
chrome-use --profile ~/.myapp open example.com # Persistent custom profile
|
|
chrome-use profiles # List available Chrome profiles
|
|
chrome-use --session-name myapp open example.com # Auto-save/restore state
|
|
chrome-use chat "open google.com and search for cats" # AI chat (single-shot)
|
|
chrome-use chat # AI chat (interactive REPL)
|
|
chrome-use -q chat "summarize this page" # Quiet mode (text only)
|
|
|
|
Command Chaining:
|
|
Chain commands with && in a single shell call (browser persists via daemon):
|
|
|
|
chrome-use open example.com && chrome-use snapshot -i
|
|
chrome-use fill @e1 "user@example.com" && chrome-use fill @e2 "pass" && chrome-use click @e3
|
|
chrome-use open example.com && chrome-use screenshot
|
|
|
|
iOS Simulator (requires Xcode and Appium):
|
|
chrome-use -p ios open example.com # Use default iPhone
|
|
chrome-use -p ios --device "iPhone 15 Pro" open url # Specific device
|
|
chrome-use -p ios device list # List simulators
|
|
chrome-use -p ios swipe up # Swipe gesture
|
|
chrome-use -p ios tap @e1 # Touch element
|
|
"#
|
|
);
|
|
}
|
|
|
|
fn print_snapshot_diff(data: &serde_json::Map<String, serde_json::Value>) {
|
|
let changed = data
|
|
.get("changed")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
if !changed {
|
|
println!("{} No changes detected", color::success_indicator());
|
|
return;
|
|
}
|
|
if let Some(diff) = data.get("diff").and_then(|v| v.as_str()) {
|
|
for line in diff.lines() {
|
|
if line.starts_with("+ ") {
|
|
println!("{}", color::green(line));
|
|
} else if line.starts_with("- ") {
|
|
println!("{}", color::red(line));
|
|
} else {
|
|
println!("{}", color::dim(line));
|
|
}
|
|
}
|
|
let additions = data.get("additions").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let removals = data.get("removals").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
let unchanged = data.get("unchanged").and_then(|v| v.as_i64()).unwrap_or(0);
|
|
println!(
|
|
"\n{} additions, {} removals, {} unchanged",
|
|
color::green(&additions.to_string()),
|
|
color::red(&removals.to_string()),
|
|
unchanged
|
|
);
|
|
}
|
|
}
|
|
|
|
fn print_screenshot_diff(data: &serde_json::Map<String, serde_json::Value>) {
|
|
let mismatch = data
|
|
.get("mismatchPercentage")
|
|
.and_then(|v| v.as_f64())
|
|
.unwrap_or(0.0);
|
|
let is_match = data.get("match").and_then(|v| v.as_bool()).unwrap_or(false);
|
|
let dim_mismatch = data
|
|
.get("dimensionMismatch")
|
|
.and_then(|v| v.as_bool())
|
|
.unwrap_or(false);
|
|
if dim_mismatch {
|
|
println!(
|
|
"{} Images have different dimensions",
|
|
color::error_indicator()
|
|
);
|
|
} else if is_match {
|
|
println!(
|
|
"{} Images match (0% difference)",
|
|
color::success_indicator()
|
|
);
|
|
} else {
|
|
println!(
|
|
"{} {:.2}% pixels differ",
|
|
color::error_indicator(),
|
|
mismatch
|
|
);
|
|
}
|
|
if let Some(diff_path) = data.get("diffPath").and_then(|v| v.as_str()) {
|
|
println!(" Diff image: {}", color::green(diff_path));
|
|
}
|
|
let total = data
|
|
.get("totalPixels")
|
|
.and_then(|v| v.as_i64())
|
|
.unwrap_or(0);
|
|
let different = data
|
|
.get("differentPixels")
|
|
.and_then(|v| v.as_i64())
|
|
.unwrap_or(0);
|
|
println!(
|
|
" {} different / {} total pixels",
|
|
color::red(&different.to_string()),
|
|
total
|
|
);
|
|
}
|
|
|
|
pub fn print_version() {
|
|
println!("chrome-use {}", env!("CARGO_PKG_VERSION"));
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::format_storage_text;
|
|
use serde_json::json;
|
|
|
|
#[test]
|
|
fn test_format_stream_status_text_for_enabled_stream() {
|
|
let data = json!({
|
|
"enabled": true,
|
|
"port": 9223,
|
|
"connected": true,
|
|
"screencasting": false
|
|
});
|
|
|
|
let rendered = super::format_stream_status_text(Some("stream_status"), &data).unwrap();
|
|
|
|
assert_eq!(
|
|
rendered,
|
|
"Streaming enabled on ws://127.0.0.1:9223\nConnected: true\nScreencasting: false"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn test_format_stream_status_text_for_disabled_stream() {
|
|
let data =
|
|
json!({ "enabled": false, "port": null, "connected": false, "screencasting": false });
|
|
|
|
let rendered = super::format_stream_status_text(Some("stream_status"), &data).unwrap();
|
|
|
|
assert_eq!(rendered, "Streaming disabled");
|
|
}
|
|
|
|
#[test]
|
|
fn test_format_storage_text_for_all_entries() {
|
|
let data = json!({
|
|
"data": {
|
|
"token": "abc123",
|
|
"user": "alice"
|
|
}
|
|
});
|
|
|
|
let rendered = format_storage_text(&data).unwrap();
|
|
|
|
assert_eq!(rendered, "token: abc123\nuser: alice");
|
|
}
|
|
|
|
#[test]
|
|
fn test_format_storage_text_for_key_lookup() {
|
|
let data = json!({
|
|
"key": "token",
|
|
"value": "abc123"
|
|
});
|
|
|
|
let rendered = format_storage_text(&data).unwrap();
|
|
|
|
assert_eq!(rendered, "token: abc123");
|
|
}
|
|
|
|
#[test]
|
|
fn test_format_storage_text_for_empty_store() {
|
|
let data = json!({
|
|
"data": {}
|
|
});
|
|
|
|
let rendered = format_storage_text(&data).unwrap();
|
|
|
|
assert_eq!(rendered, "No storage entries");
|
|
}
|
|
}
|