refactor(browser): share tab reference CLI help

2026-06-03 12:44:06 +00:00 · 2026-05-31 10:03:34 +08:00
parent 2e1b0becea
commit 118af80b0b
11 changed files with 90 additions and 208 deletions
--- a/extensions/browser/src/cli/browser-cli-actions-input/register.element.ts
+++ b/extensions/browser/src/cli/browser-cli-actions-input/register.element.ts
@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  parseBrowserNonNegativeIntegerOption,
  parseBrowserPositiveIntegerOption,
  type BrowserParentOpts,
@@ -65,10 +66,7 @@ export function registerBrowserElementCommands(
    .command("click")
    .description("Click an element by ref from snapshot")
    .argument("<ref>", "Ref id from snapshot")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option("--double", "Double click", false)
    .option("--button <left|right|middle>", "Mouse button to use")
    .option("--modifiers <list>", "Comma-separated modifiers (Shift,Alt,Meta)")
@@ -106,10 +104,7 @@ export function registerBrowserElementCommands(
    .description("Click viewport coordinates")
    .argument("<x>", "Viewport x coordinate")
    .argument("<y>", "Viewport y coordinate")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option("--double", "Double click", false)
    .option("--button <left|right|middle>", "Mouse button to use")
    .option("--delay-ms <ms>", "Delay between mouse down/up", (v: string) =>
@@ -147,10 +142,7 @@ export function registerBrowserElementCommands(
    .argument("<text>", "Text to type")
    .option("--submit", "Press Enter after typing", false)
    .option("--slowly", "Type slowly (human-like)", false)
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (ref: string | undefined, text: string, opts, cmd) => {
      const refValue = requireRef(ref);
      if (!refValue) {
@@ -174,10 +166,7 @@ export function registerBrowserElementCommands(
    .command("press")
    .description("Press a key")
    .argument("<key>", "Key to press (e.g. Enter)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (key: string, opts, cmd) => {
      await runElementAction({
        cmd,
@@ -190,10 +179,7 @@ export function registerBrowserElementCommands(
    .command("hover")
    .description("Hover an element by ai ref")
    .argument("<ref>", "Ref id from snapshot")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (ref: string, opts, cmd) => {
      await runElementAction({
        cmd,
@@ -206,10 +192,7 @@ export function registerBrowserElementCommands(
    .command("scrollintoview")
    .description("Scroll an element into view by ref from snapshot")
    .argument("<ref>", "Ref id from snapshot")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option("--timeout-ms <ms>", "How long to wait for scroll (default: 20000)", (v: string) =>
      parseBrowserPositiveIntegerOption(v, "--timeout-ms"),
    )
@@ -237,10 +220,7 @@ export function registerBrowserElementCommands(
    .description("Drag from one ref to another")
    .argument("<startRef>", "Start ref id")
    .argument("<endRef>", "End ref id")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (startRef: string, endRef: string, opts, cmd) => {
      await runElementAction({
        cmd,
@@ -259,10 +239,7 @@ export function registerBrowserElementCommands(
    .description("Select option(s) in a select element")
    .argument("<ref>", "Ref id from snapshot")
    .argument("<values...>", "Option values to select")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (ref: string, values: string[], opts, cmd) => {
      await runElementAction({
        cmd,
--- a/extensions/browser/src/cli/browser-cli-actions-input/register.files-downloads.ts
+++ b/extensions/browser/src/cli/browser-cli-actions-input/register.files-downloads.ts
@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  callBrowserRequest,
  parseBrowserPositiveIntegerOption,
  type BrowserParentOpts,
@@ -95,10 +96,7 @@ export function registerBrowserFilesAndDownloadsCommands(
    .option("--ref <ref>", "Ref id from snapshot to click after arming")
    .option("--input-ref <ref>", "Ref id for <input type=file> to set directly")
    .option("--element <selector>", "CSS selector for <input type=file>")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option(
      "--timeout-ms <ms>",
      "How long to wait for the next file chooser (default: 120000)",
@@ -137,10 +135,7 @@ export function registerBrowserFilesAndDownloadsCommands(
      "[path]",
      "Save path within openclaw temp downloads dir (default: /tmp/openclaw/downloads/...; fallback: os.tmpdir()/openclaw/downloads/...)",
    )
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option(
      "--timeout-ms <ms>",
      "How long to wait for the next download (default: 120000)",
@@ -163,10 +158,7 @@ export function registerBrowserFilesAndDownloadsCommands(
      "<path>",
      "Save path within openclaw temp downloads dir (e.g. report.pdf or /tmp/openclaw/downloads/report.pdf)",
    )
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option(
      "--timeout-ms <ms>",
      "How long to wait for the download to start (default: 120000)",
@@ -189,10 +181,7 @@ export function registerBrowserFilesAndDownloadsCommands(
    .option("--dismiss", "Dismiss the dialog", false)
    .option("--prompt <text>", "Prompt response text")
    .option("--dialog-id <id>", "Pending dialog id from snapshot/browser state")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option(
      "--timeout-ms <ms>",
      "How long to wait for the next dialog (default: 120000)",
--- a/extensions/browser/src/cli/browser-cli-actions-input/register.form-wait-eval.ts
+++ b/extensions/browser/src/cli/browser-cli-actions-input/register.form-wait-eval.ts
@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  parseBrowserNonNegativeIntegerOption,
  parseBrowserPositiveIntegerOption,
  type BrowserParentOpts,
@@ -39,10 +40,7 @@ export function registerBrowserFormWaitEvalCommands(
    .description("Fill a form with JSON field descriptors")
    .option("--fields <json>", "JSON array of field objects")
    .option("--fields-file <path>", "Read JSON array from a file")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
      try {
@@ -83,10 +81,7 @@ export function registerBrowserFormWaitEvalCommands(
      "How long to wait for each condition (default: 20000)",
      (v: string) => parseBrowserPositiveIntegerOption(v, "--timeout-ms"),
    )
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (selector: string | undefined, opts, cmd) => {
      const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
      try {
@@ -136,10 +131,7 @@ export function registerBrowserFormWaitEvalCommands(
      "How long to allow the evaluate function to run (default: 20000)",
      (v: string) => parseBrowserPositiveIntegerOption(v, "--timeout-ms"),
    )
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
      if (!opts.fn) {
--- a/extensions/browser/src/cli/browser-cli-actions-input/register.navigation.ts
+++ b/extensions/browser/src/cli/browser-cli-actions-input/register.navigation.ts
@@ -3,6 +3,7 @@ import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runti
 import { ACT_MAX_VIEWPORT_DIMENSION } from "../../browser/act-policy.js";
 import { runBrowserResizeWithOutput } from "../browser-cli-resize.js";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  callBrowserRequest,
  parseBrowserPositiveIntegerValue,
  type BrowserParentOpts,
@@ -33,10 +34,7 @@ export function registerBrowserNavigationCommands(
    .command("navigate")
    .description("Navigate the current tab to a URL")
    .argument("<url>", "URL to navigate to")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (url: string, opts, cmd) => {
      const { parent, profile } = resolveBrowserActionContext(cmd, parentOpts);
      try {
@@ -69,10 +67,7 @@ export function registerBrowserNavigationCommands(
    .description("Resize the viewport")
    .argument("<width>", "Viewport width")
    .argument("<height>", "Viewport height")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (width: string, height: string, opts, cmd) => {
      const normalizedWidth = parsePositiveInteger(width, "width");
      const normalizedHeight = parsePositiveInteger(height, "height");
--- a/extensions/browser/src/cli/browser-cli-actions-observe.ts
+++ b/extensions/browser/src/cli/browser-cli-actions-observe.ts
@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { runCommandWithRuntime } from "../core-api.js";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  callBrowserRequest,
  parseBrowserPositiveIntegerOption,
  type BrowserParentOpts,
@@ -23,10 +24,7 @@ export function registerBrowserActionObserveCommands(
    .command("console")
    .description("Get recent console messages")
    .option("--level <level>", "Filter by level (error, warn, info)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      const parent = parentOpts(cmd);
      const profile = parent?.browserProfile;
@@ -55,10 +53,7 @@ export function registerBrowserActionObserveCommands(
  browser
    .command("pdf")
    .description("Save page as PDF")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      const parent = parentOpts(cmd);
      const profile = parent?.browserProfile;
@@ -85,10 +80,7 @@ export function registerBrowserActionObserveCommands(
    .command("responsebody")
    .description("Wait for a network response and return its body")
    .argument("<url>", "URL (exact, substring, or glob like **/api)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option(
      "--timeout-ms <ms>",
      "How long to wait for the response (default: 20000)",
--- a/extensions/browser/src/cli/browser-cli-debug.ts
+++ b/extensions/browser/src/cli/browser-cli-debug.ts
@@ -1,7 +1,11 @@
 import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { runCommandWithRuntime } from "../core-api.js";
-import { callBrowserRequest, type BrowserParentOpts } from "./browser-cli-shared.js";
+import {
+  BROWSER_TAB_REFERENCE_HELP,
+  callBrowserRequest,
+  type BrowserParentOpts,
+} from "./browser-cli-shared.js";
 import { danger, defaultRuntime, shortenHomePath } from "./core-api.js";

 const BROWSER_DEBUG_TIMEOUT_MS = 20000;
@@ -75,10 +79,7 @@ export function registerBrowserDebugCommands(
    .command("highlight")
    .description("Highlight an element by ref")
    .argument("<ref>", "Ref id from snapshot")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (ref: string, opts, cmd) => {
      await withDebugContext(cmd, parentOpts, async ({ parent, profile }) => {
        const result = await callDebugRequest(parent, {
@@ -101,10 +102,7 @@ export function registerBrowserDebugCommands(
    .command("errors")
    .description("Get recent page errors")
    .option("--clear", "Clear stored errors after reading", false)
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      await withDebugContext(cmd, parentOpts, async ({ parent, profile }) => {
        const result = await callDebugRequest<{
@@ -138,10 +136,7 @@ export function registerBrowserDebugCommands(
    .description("Get recent network requests (best-effort)")
    .option("--filter <text>", "Only show URLs that contain this substring")
    .option("--clear", "Clear stored requests after reading", false)
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      await withDebugContext(cmd, parentOpts, async ({ parent, profile }) => {
        const result = await callDebugRequest<{
@@ -188,10 +183,7 @@ export function registerBrowserDebugCommands(
  trace
    .command("start")
    .description("Start trace recording")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option("--no-screenshots", "Disable screenshots")
    .option("--no-snapshots", "Disable snapshots")
    .option("--sources", "Include sources (bigger traces)", false)
@@ -222,10 +214,7 @@ export function registerBrowserDebugCommands(
      "--out <path>",
      "Output path within openclaw temp dir (e.g. trace.zip or /tmp/openclaw/trace.zip)",
    )
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      await withDebugContext(cmd, parentOpts, async ({ parent, profile }) => {
        const result = await callDebugRequest<{ path: string }>(parent, {
--- a/extensions/browser/src/cli/browser-cli-inspect.ts
+++ b/extensions/browser/src/cli/browser-cli-inspect.ts
@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  callBrowserRequest,
  parseBrowserNonNegativeIntegerValue,
  parseBrowserPositiveIntegerValue,
@@ -42,10 +43,7 @@ export function registerBrowserInspectCommands(
  browser
    .command("screenshot")
    .description("Capture a screenshot (prints the saved path)")
-    .argument(
-      "[targetId]",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .argument("[targetId]", BROWSER_TAB_REFERENCE_HELP)
    .option("--full-page", "Capture full scrollable page", false)
    .option("--ref <ref>", "ARIA ref from ai snapshot")
    .option("--element <selector>", "CSS selector for element screenshot")
@@ -87,10 +85,7 @@ export function registerBrowserInspectCommands(
    .command("snapshot")
    .description("Capture a snapshot (default: ai; aria is the accessibility tree)")
    .option("--format <aria|ai>", "Snapshot format (default: ai)", "ai")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .option("--limit <n>", "Max nodes (default: 500/800)")
    .option("--mode <efficient>", "Snapshot preset (efficient)")
    .option("--efficient", "Use the efficient snapshot preset", false)
--- a/extensions/browser/src/cli/browser-cli-manage.ts
+++ b/extensions/browser/src/cli/browser-cli-manage.ts
@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { runCommandWithRuntime } from "../core-api.js";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  callBrowserRequest,
  parseBrowserPositiveIntegerValue,
  type BrowserParentOpts,
@@ -484,10 +485,7 @@ export function registerBrowserManageCommands(
  tab
    .command("label")
    .description("Assign a friendly label to a tab")
-    .argument(
-      "<targetId>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .argument("<targetId>", BROWSER_TAB_REFERENCE_HELP)
    .argument("<label>", "Friendly label")
    .action(async (targetId: string, label: string, _opts, cmd) => {
      const parent = parentOpts(cmd);
@@ -579,10 +577,7 @@ export function registerBrowserManageCommands(
  browser
    .command("focus")
    .description("Focus a tab by tab reference")
-    .argument(
-      "<targetId>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .argument("<targetId>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (targetId: string, _opts, cmd) => {
      const parent = parentOpts(cmd);
      const profile = parent?.browserProfile;
@@ -607,10 +602,7 @@ export function registerBrowserManageCommands(
  browser
    .command("close")
    .description("Close a tab (tab reference optional)")
-    .argument(
-      "[targetId]",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix (optional)",
-    )
+    .argument("[targetId]", `${BROWSER_TAB_REFERENCE_HELP} (optional)`)
    .action(async (targetId: string | undefined, _opts, cmd) => {
      const parent = parentOpts(cmd);
      const profile = parent?.browserProfile;
--- a/extensions/browser/src/cli/browser-cli-shared.ts
+++ b/extensions/browser/src/cli/browser-cli-shared.ts
@@ -15,6 +15,9 @@ export type BrowserParentOpts = GatewayRpcOpts & {
  browserProfile?: string;
 };

+export const BROWSER_TAB_REFERENCE_HELP =
+  "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix";
+
 type BrowserRequestParams = {
  method: "GET" | "POST" | "DELETE";
  path: string;
--- a/extensions/browser/src/cli/browser-cli-state.cookies-storage.ts
+++ b/extensions/browser/src/cli/browser-cli-state.cookies-storage.ts
@@ -1,6 +1,10 @@
 import type { Command } from "commander";
 import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
-import { callBrowserRequest, type BrowserParentOpts } from "./browser-cli-shared.js";
+import {
+  BROWSER_TAB_REFERENCE_HELP,
+  callBrowserRequest,
+  type BrowserParentOpts,
+} from "./browser-cli-shared.js";
 import { danger, defaultRuntime, inheritOptionFromParent } from "./core-api.js";

 function resolveUrl(opts: { url?: string }, command: Command): string | undefined {
@@ -41,38 +45,33 @@ export function registerBrowserCookiesAndStorageCommands(
 ) {
  const cookies = browser.command("cookies").description("Read/write cookies");

-  cookies
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
-    .action(async (opts, cmd) => {
-      const parent = parentOpts(cmd);
-      const profile = parent?.browserProfile;
-      const targetId = resolveTargetId(opts.targetId, cmd);
-      try {
-        const result = await callBrowserRequest<{ cookies?: unknown[] }>(
-          parent,
-          {
-            method: "GET",
-            path: "/cookies",
-            query: {
-              targetId,
-              profile,
-            },
+  cookies.option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP).action(async (opts, cmd) => {
+    const parent = parentOpts(cmd);
+    const profile = parent?.browserProfile;
+    const targetId = resolveTargetId(opts.targetId, cmd);
+    try {
+      const result = await callBrowserRequest<{ cookies?: unknown[] }>(
+        parent,
+        {
+          method: "GET",
+          path: "/cookies",
+          query: {
+            targetId,
+            profile,
          },
-          { timeoutMs: 20000 },
-        );
-        if (parent?.json) {
-          defaultRuntime.writeJson(result);
-          return;
-        }
-        defaultRuntime.writeJson(result.cookies ?? []);
-      } catch (err) {
-        defaultRuntime.error(danger(String(err)));
-        defaultRuntime.exit(1);
+        },
+        { timeoutMs: 20000 },
+      );
+      if (parent?.json) {
+        defaultRuntime.writeJson(result);
+        return;
      }
-    });
+      defaultRuntime.writeJson(result.cookies ?? []);
+    } catch (err) {
+      defaultRuntime.error(danger(String(err)));
+      defaultRuntime.exit(1);
+    }
+  });

  cookies
    .command("set")
@@ -80,10 +79,7 @@ export function registerBrowserCookiesAndStorageCommands(
    .argument("<name>", "Cookie name")
    .argument("<value>", "Cookie value")
    .option("--url <url>", "Cookie URL scope (recommended)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (name: string, value: string, opts, cmd) => {
      const parent = parentOpts(cmd);
      const profile = parent?.browserProfile;
@@ -112,10 +108,7 @@ export function registerBrowserCookiesAndStorageCommands(
  cookies
    .command("clear")
    .description("Clear all cookies")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (opts, cmd) => {
      const parent = parentOpts(cmd);
      const profile = parent?.browserProfile;
@@ -143,10 +136,7 @@ export function registerBrowserCookiesAndStorageCommands(
      .command("get")
      .description(`Get ${kind}Storage (all keys or one key)`)
      .argument("[key]", "Key (optional)")
-      .option(
-        "--target-id <id>",
-        "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-      )
+      .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
      .action(async (key: string | undefined, opts, cmd2) => {
        const parent = parentOpts(cmd2);
        const profile = parent?.browserProfile;
@@ -181,10 +171,7 @@ export function registerBrowserCookiesAndStorageCommands(
      .description(`Set a ${kind}Storage key`)
      .argument("<key>", "Key")
      .argument("<value>", "Value")
-      .option(
-        "--target-id <id>",
-        "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-      )
+      .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
      .action(async (key: string, value: string, opts, cmd2) => {
        const parent = parentOpts(cmd2);
        const profile = parent?.browserProfile;
@@ -208,10 +195,7 @@ export function registerBrowserCookiesAndStorageCommands(
    cmd
      .command("clear")
      .description(`Clear all ${kind}Storage keys`)
-      .option(
-        "--target-id <id>",
-        "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-      )
+      .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
      .action(async (opts, cmd2) => {
        const parent = parentOpts(cmd2);
        const profile = parent?.browserProfile;
--- a/extensions/browser/src/cli/browser-cli-state.ts
+++ b/extensions/browser/src/cli/browser-cli-state.ts
@@ -7,6 +7,7 @@ import { ACT_MAX_VIEWPORT_DIMENSION } from "../browser/act-policy.js";
 import { runCommandWithRuntime } from "../core-api.js";
 import { runBrowserResizeWithOutput } from "./browser-cli-resize.js";
 import {
+  BROWSER_TAB_REFERENCE_HELP,
  callBrowserRequest,
  parseBrowserPositiveIntegerValue,
  type BrowserParentOpts,
@@ -96,10 +97,7 @@ export function registerBrowserStateCommands(
    .description("Set viewport size (alias for resize)")
    .argument("<width>", "Viewport width")
    .argument("<height>", "Viewport height")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (widthRaw: string, heightRaw: string, opts, cmd) => {
      const width = parsePositiveInteger(widthRaw, "width");
      const height = parsePositiveInteger(heightRaw, "height");
@@ -125,10 +123,7 @@ export function registerBrowserStateCommands(
    .command("offline")
    .description("Toggle offline mode")
    .argument("<on|off>", "on/off")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (value: string, opts, cmd) => {
      const parent = parentOpts(cmd);
      const offline = parseOnOff(value);
@@ -153,10 +148,7 @@ export function registerBrowserStateCommands(
    .description("Set extra HTTP headers (JSON object)")
    .argument("[headersJson]", "JSON object of headers (alternative to --headers-json)")
    .option("--headers-json <json>", "JSON object of headers")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (headersJson: string | undefined, opts, cmd) => {
      const parent = parentOpts(cmd);
      await runBrowserCommand(async () => {
@@ -203,10 +195,7 @@ export function registerBrowserStateCommands(
    .option("--clear", "Clear credentials", false)
    .argument("[username]", "Username")
    .argument("[password]", "Password")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (username: string | undefined, password: string | undefined, opts, cmd) => {
      const parent = parentOpts(cmd);
      await runBrowserSetRequest({
@@ -230,10 +219,7 @@ export function registerBrowserStateCommands(
    .argument("[longitude]", "Longitude")
    .option("--accuracy <m>", "Accuracy in meters")
    .option("--origin <origin>", "Origin to grant permissions for")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(
      async (latitudeRaw: string | undefined, longitudeRaw: string | undefined, opts, cmd) => {
        const parent = parentOpts(cmd);
@@ -267,10 +253,7 @@ export function registerBrowserStateCommands(
    .command("media")
    .description("Emulate prefers-color-scheme")
    .argument("<dark|light|none>", "dark/light/none")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (value: string, opts, cmd) => {
      const parent = parentOpts(cmd);
      const v = normalizeOptionalLowercaseString(value);
@@ -296,10 +279,7 @@ export function registerBrowserStateCommands(
    .command("timezone")
    .description("Override timezone (CDP)")
    .argument("<timezoneId>", "Timezone ID (e.g. America/New_York)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (timezoneId: string, opts, cmd) => {
      const parent = parentOpts(cmd);
      await runBrowserSetRequest({
@@ -317,10 +297,7 @@ export function registerBrowserStateCommands(
    .command("locale")
    .description("Override locale (CDP)")
    .argument("<locale>", "Locale (e.g. en-US)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (locale: string, opts, cmd) => {
      const parent = parentOpts(cmd);
      await runBrowserSetRequest({
@@ -338,10 +315,7 @@ export function registerBrowserStateCommands(
    .command("device")
    .description('Apply a Playwright device descriptor (e.g. "iPhone 14")')
    .argument("<name>", "Device name (Playwright devices)")
-    .option(
-      "--target-id <id>",
-      "Tab reference: suggested target id, tab id, label, raw target id, or unique raw prefix",
-    )
+    .option("--target-id <id>", BROWSER_TAB_REFERENCE_HELP)
    .action(async (name: string, opts, cmd) => {
      const parent = parentOpts(cmd);
      await runBrowserSetRequest({