Commands

page.runCommand(command) parses one agent-browser style command line, runs it on the page and returns an AgentCommandResult. It is the smallest surface you can hand to an LLM: one string in, one string out.

val result = page.runCommand("snapshot -i")
result.output     // text for the model
result.snapshot   // the Snapshot, for snapshot commands
result.screenshot // the ScreenshotResult, for screenshot commands

agent-browser: the same command names and ref syntax as the agent-browser CLI, minus the CLI's session and daemon commands. The unsupported commands section maps each missing one to the typed API.

AgentCommandResultCopy Anchor Link

runCommand is a suspending extension on Page. It throws KmpwrightException for unknown or malformed commands and propagates the exception of the underlying call (for example KmpwrightTimeoutException when a target never becomes actionable). Return e.message to the model; see Errors are written for the model.

SyntaxCopy Anchor Link

<command> [arguments...] [flags...]

• The command name is case-insensitive (CLICK works). Sub-arguments such as get TEXT, is Visible, scroll Down, cookies Clear and storage Local are case-insensitive too.
• Flags are case-sensitive and must match exactly: -c is compact, -C is cursor. They can appear anywhere after the command name. Unknown flags and extra arguments are ignored.
• Targets are a snapshot ref (@e3, e3 or ref=e3) or any selector page.locator understands: CSS (#email), text=Save, role=button[name="Save"], label=Email, placeholder=…, testid=…, xpath=…, and >> chains.
• Commands that take free text (fill, type, select, eval) join all remaining arguments with a single space, so fill @e2 hello world fills hello world. Quote the text to keep repeated spaces.
• Flag values are a single argument. Quote values with spaces: wait --text "Welcome back", wait --fn "document.readyState === 'complete'", snapshot -s "#cart .items". Unquoted, wait --text Welcome back waits for Welcome only.

Quoting and escapingCopy Anchor Link

AgentCommands.tokenize(command) splits the line. It is public, so you can use it to pre-parse commands yourself.

ErrorsCopy Anchor Link

HelpCopy Anchor Link

AgentCommands.HELP is a compact reference meant to be used verbatim as a tool description or in a system prompt:

Navigation   open <url> · back · forward · reload
Observe      snapshot [-i interactive] [-u urls] [-c compact] [-d depth] [-s selector]
             screenshot [--full] [--annotate]
Act          click|dblclick|tap|hover|focus|check|uncheck|highlight <target>
             fill <target> <text> · type <target> <text> · press <key> [target]
             select <target> <value> · drag <source> <target>
             scroll <up|down|left|right|top|bottom> [px] · scrollintoview <target>
Query        get <text|html|value|count|box|title|url> [target] · get attr <target> <name>
             is <visible|enabled|checked|focused|editable> <target>
Wait         wait <ms|target> · wait --text <text> · wait --load <load|domcontentloaded|networkidle>
             wait --fn <js>  (all accept --timeout <ms>)
Page         eval <js> · console · errors · cookies [clear] · storage <local|session> [clear]

Targets are snapshot refs such as @e3, or any selector: css, text=Save, role=button, label=Email.

NavigationCopy Anchor Link

• open waits for the load state with TimeoutConfig.navigation. The output uses the URL after redirects and adds — <title> only when the title is not blank. A failed navigation (NavigationResult.ok == false) throws with the backend's error, or Navigation to <url> failed.
• back and forward report the current URL even when there is no history entry (the typed calls return null in that case).

URL normalizationCopy Anchor Link

open passes its argument through AgentCommands.normalizeUrl, which is public:

The input is trimmed first. 10.0.2.2 is the Android emulator's alias for the host machine, so open 10.0.2.2:8080 reaches a dev server on your computer.

SnapshotCopy Anchor Link

page.runCommand("snapshot -i").output
// @e1 [heading] "Example Domain" [level=1]
// @e2 [input type="email"] placeholder="Email"
// @e3 [checkbox] "Remember me" [checked]
// @e4 [button] "Later" [disabled]
// @e5 [button] "Submit"
// @e6 [link] "Learn more"

page.runCommand("snapshot -i -s #checkout")
// same as
page.snapshot(interactive = true, selector = "#checkout")

includeHidden has no flag; use the typed API. -C is accepted but not listed in AgentCommands.HELP. result.snapshot carries the full Snapshot, and the refs it contains replace the previous snapshot's refs. The format is described in Snapshots and refs.

InteractionCopy Anchor Link

Every action resolves its target, waits until it is attached, visible, enabled, stable and receives the pointer (fill: editable), and retries until TimeoutConfig.action (30 s by default). runCommand has no per-command timeout for actions; set it in KmpwrightConfig(timeouts = TimeoutConfig(action = …)).

Aliases: key for press, scrollinto for scrollintoview.

• fill replaces the value. With no text it fills an empty string, which clears the field. type requires text and sends key events one character at a time (Playwright pressSequentially), for inputs that react to each keystroke.
• press takes key names and combinations such as Enter, Tab, Escape, ArrowDown, Control+A or Shift+Tab. Without a target the key goes to the focused element. Note the argument order: key first, target second (press Enter @e2).
• select picks the <option> whose value or label equals the text. It selects one option; use selectOption(listOf(...)) for multi-selects.
• highlight draws a red overlay on the element for 3 seconds (locator.highlight() defaults). It is for a person watching the screen.

ScrollCopy Anchor Link

px defaults to 300 and scrolls exactly that many CSS pixels. A non-numeric px falls back to 300. top and bottom ignore it. Any other direction throws Usage: scroll <up|down|left|right|top|bottom> [pixels].

QueriesCopy Anchor Link

get title reads Page.title, the title as of the last navigation. If the page changes document.title later, use eval document.title.

Queries do not wait for the target. When it does not exist (including a stale ref) they answer immediately:

is checked on an element that is not a checkbox or radio throws Element <target> is not a checkbox or radio button. A selector matching several elements throws a strict-mode error for every query except get count. Use wait <target> first when the element may still be loading.

WaitCopy Anchor Link

• --timeout <ms> applies to every form except wait <ms>. It defaults to 10 000 ms, not to TimeoutConfig.
• Load states: load, domcontentloaded (or dom), networkidle (or idle). These map to LoadState.Load, LoadState.DOMContentLoaded and LoadState.NetworkIdle.
• When several flags are given, the first match wins in this order: --text, --fn, --load, then a numeric first argument, then a target.
• Put the target first: wait @e3 --timeout 5000. In wait --timeout 5000 @e3, the first argument --timeout is taken as the target.
• --text matches a substring of document.body.innerText. --fn needs allowEval.
• On timeout these throw KmpwrightTimeoutException, for example Timeout 10000ms exceeded waiting for text "Welcome".

ScreenshotCopy Anchor Link

Short flags: -f for --full, -a for --annotate; they combine. The image is a PNG in result.screenshot.bytes; the command takes no file path. Send the bytes to the model as an image (see LLM tools).

--annotate takes a fresh default snapshot first (which replaces the current refs), draws each ref's label on the page, captures, and removes the labels. The legend lists one line per labelled element; the same data is in result.screenshot.annotations (ref, role, name, box).

Screenshot 756×469
[1] @e1 heading "Example Domain"
[2] @e2 textbox "Email"
[3] @e3 checkbox "Remember me"
[4] @e4 button "Submit"
[5] @e5 link "Learn more"

Each legend line is [N] @eN <role> "<name>": the label drawn on the image is the ref number N. The role comes from the snapshot's RefEntry.role, so a text input shows as textbox here even when the tree prints [input type="email"]. Names are JSON-quoted and truncated like snapshot names; an empty name is omitted.

Page state and debuggingCopy Anchor Link

• cookies get and cookies list are the same as cookies. Any other sub-command throws Usage: cookies [list|clear].
• eval awaits Promises. It fails when KmpwrightConfig.allowEval is false or an ActionPolicy denies ActionType.Evaluate.
• console and errors cover messages since the last navigation.

Not available in runCommandCopy Anchor Link

These agent-browser commands have no runCommand form. Most have a typed equivalent you can call from your own code, or expose as an extra tool. Backend support follows PageCapabilities.

To give a model one of these, add a separate tool for it, or extend your tool function: check the first token with AgentCommands.tokenize(command) and handle your own commands before falling back to runCommand.

suspend fun Page.browserTool(command: String): String {
    return try {
        val args = AgentCommands.tokenize(command)
        when (args.firstOrNull()?.lowercase()) {
            "upload" -> {
                val target = args.getOrNull(1) ?: return "Error: Usage: upload <target> <file>..."
                locator(target).setInputFiles(args.drop(2))
                "Uploaded ${args.size - 2} file(s) to $target"
            }
            "waiturl" -> {
                val pattern = args.getOrNull(1) ?: return "Error: Usage: waiturl <glob>"
                waitForURL(pattern)
                "URL matches $pattern"
            }
            else -> runCommand(command).output
        }
    } catch (e: CancellationException) {
        throw e
    } catch (e: Exception) {
        "Error: ${e.message ?: e.toString()}"
    }
}

If you add commands, append their usage to the tool description after AgentCommands.HELP.