/cate-cli

name: cate-cli
description: Drive Cate browser, terminal, editor, panel, review, and coding-agent orchestration surfaces from a Cate terminal. Browser page automation targets Cate's live webviews directly.
user-invocable: true

Cate CLI

`cate` is available inside Cate terminals and agent shells. It talks to the current workspace and requires the relevant Settings → CLI permission.

Start by listing panels:

cate panel list

When working repeatedly with one panel, select it for the current agent or terminal session:

cate panel set 1a2b3c4d
cate panel current

The selection is isolated by a per-terminal CLI session, so other agents and terminals keep their own targets. Short ids from `panel list` are accepted. Use `--panel <id>` only as a one-command override. Clear the selection to return to Cate's automatic focused/grouped resolution:

cate panel clear

Selections can point to any native panel. Browser and terminal commands reject a selected panel of the wrong type instead of silently controlling another panel. If a selected panel was closed, select another panel before continuing.

Browser workflow

To open a new browser panel, use the panel command. The URL is optional:

cate panel create browser https://example.com
cate panel create browser

Use `cate browser run` to inspect and control a panel's live tab, or to open another tab within an existing browser panel.

Browser control uses persistent JavaScript with the `cua` tab API. The old argv actions, selectors, page evaluation, and revisioned string refs have been removed. Start by binding a tab to get its accessibility state, then request a screenshot when visual context is useful:

cate browser run 'var tab = await cua.getTab({panelId:"<full-panel-id>"});'
cate browser run 'await tab.getAXStateAndScreenshot();'

Use full panel IDs inside JavaScript. `--panel <id>` supports short IDs as an override for CLI panel resolution. Discover tabs with `await cua.listTabs()`. Create a tab with `await cua.createBrowserTab("https://example.com")`, or pass `{panelId:tab.panelId}` as the second argument to choose its panel. Use the full panel ID inside JavaScript. If no browser panel exists, create one with `cate panel create browser [url]` first. Bindings pin both panel and tab; they never silently follow a user's tab switch.

Use numeric IDs from the latest AX observation. For example, after observing a form containing textbox 17 and button 42:

cate browser run 'await tab.setValue(17,"user@example.com"); await tab.click(42); await tab.waitFor({url:"**/dashboard"});'
cate browser run 'await tab.getAXStateAndScreenshot();'

Do not guess IDs or coordinates. Observations contain `kind`, `observationId`, `documentId`, URL, title and viewport. AX observations (`kind:"ax"`) also contain accessibility state and structured elements with role, name, value and states. `getAXState()` normally emits a concise diff; `getAXState({disableDiffing:true})` emits the full tree. `getScreenshot()` returns only viewport pixels/identity (`kind:"image"`, empty state/elements), avoiding an AX scan. It does not refresh numeric IDs. `getAXStateAndScreenshot()` refreshes both together. The SDK keeps the last AX observation for numeric targets and the latest visual observation for coordinates. `{emit:false}` suppresses automatic output. `{profile:true}` adds phase timings, image bytes and estimated retained-cache usage. Each code cell retains at most 16 million serialized observation characters, including `emit:false`; split long screenshot loops across cells.

The SDK carries the latest observation through each action and emits fresh state. Numeric IDs persist within one document; navigation requires fresh IDs. Coordinate actions use `[x,y]` in observed viewport CSS pixels and reject stale viewport coordinates. A dispatched click is not proof that a business operation completed: use `waitFor` or inspect the resulting state.

const src = await tab.getAttribute(42, "src"); // string or null; use a current AX element ID
await tab.download(src);                       // relative URLs resolve against the current page
await tab.click(42);                         // or [x,y]
await tab.setValue(17, "replacement");
await tab.typeText("insert at selection");
await tab.pressKey("Return");
await tab.selectText(17, "text", {selectionType:"cursor_after"});
await tab.scroll([400,300], "down", 1);
await tab.drag([100,100], [300,200]);
await tab.setChecked(42, true);
await tab.selectOption(42, ["DE"]);
await tab.upload(42, "/authorized/file");
await tab.waitFor({text:"Saved"});
await tab.waitFor({element:42, state:"enabled"});
await tab.goto("https://example.com");
await tab.back(); await tab.forward(); await tab.reload();
await tab.setViewport({width:1280,height:800});
await tab.resize({width:800,height:600});
await tab.download();                         // current tab URL; or pass an absolute/relative asset URL
await tab.downloads();                        // inspect download progress/completion
await tab.close();

Keep deterministic batches short and inspect unexpected changes before continuing. Use `var` for reusable bindings; top-level `await` is supported. The session has no Node.js, filesystem, network, or DOM evaluation access. Await every action. `nodeRepl.write(value)` adds text output. `cate browser reset` clears JavaScript bindings without closing tabs. Reset and timeout cancel queued and pending browser actions; input already dispatched cannot be undone. Sessions are isolated per terminal/agent through `CATE_CLI_SESSION_ID`; timed-out sessions reset. `typeText` resolves current focus before inserting at the current selection, including fields inside frames and shadow roots.

`cate browser run 'await tab.getAXStateAndScreenshot();'` returns AX state and saves a screenshot to a temporary PNG file. Open the printed path with your image-viewing tool before visual reasoning. Sh