browsers Commands
Manage browsers
Output formatting flags (--json, --jq, and --template) are documented once in Output Formatting and are omitted from the tables below.
bctrl browsers computer batch
Execute up to twenty desktop actions in order on one current Browser Run. Every action is validated before acceptance. Execution stops at the first uncertain result and returns unknown with null data; earlier actions may have taken effect. Reusing the same Idempotency-Key replays the terminal result without repeating the batch.
bctrl browsers computer click
Click the current Browser Run at screenshot-pixel coordinates, or at the cursor when omitted. Button defaults to left; two or three clicks require the left button. An interrupted action returns unknown and must not be repeated automatically.
bctrl browsers computer clipboard read
Read the system clipboard of the current Browser Run as text (at most 256 KiB of UTF-8). Reading has no effect on the page. The result carries its canonical Event ID; interrupted execution returns unknown.
bctrl browsers computer clipboard write
Replace the system clipboard of the current Browser Run with text (at most 256 KiB of UTF-8, no NUL); empty text clears it. Nothing is pasted. The text is excluded from Events. Human control blocks automation; an interrupted write returns unknown.
bctrl browsers computer cursor
Read the cursor position and desktop dimensions of the current Browser Run. The result carries its canonical Event ID. Human control blocks automation; interrupted execution returns unknown.
bctrl browsers computer doubleClick
Double-click the left mouse button in the current Browser Run. Coordinates use screenshot pixels; omission uses the current cursor. An interrupted action returns unknown with its accepted Event ID.
bctrl browsers computer drag
Drag the left mouse button in the current Browser Run to the requested coordinates, with an optional starting position and bounded path. Human control blocks automation. An interrupted action returns unknown.
bctrl browsers computer key
Send one bounded key chord to the current Browser Run, with an optional repeat count. Human control blocks automation. An interrupted action returns unknown with its accepted Event ID.
bctrl browsers computer move
Move the cursor in the current Browser Run to screenshot-pixel coordinates. Human control blocks automation. An interrupted action returns unknown with its accepted Event ID.
bctrl browsers computer screenshot
Capture the headed desktop of the current Browser Run as a JPEG. The result carries its canonical Event ID. An interrupted capture returns unknown with null data.
bctrl browsers computer scroll
Scroll the current Browser Run in the requested direction by a bounded amount, optionally at screenshot-pixel coordinates. Human control blocks automation. An interrupted action returns unknown.
bctrl browsers computer type
Type text into the focused control in the current Browser Run. Text is excluded from canonical capability Events and replay results are encrypted. Human control blocks automation; an interrupted action returns unknown.
bctrl browsers computer wait
Wait up to ten seconds in the current Browser Run. Human control blocks automation. The result carries its canonical Event ID; interrupted execution returns unknown.
bctrl browsers connections revoke
Invalidate every existing connection URL for the current Run and issue connections in a new credential generation. Refresh the browser before reconnecting.
bctrl browsers control get
Read desired control and native confirmation for the current Browser Run. The holder credential is never returned. A human hold persists across restarts, while old viewer credentials cannot control a newer Run.
bctrl browsers control release
Release control held by the supplied current viewer. Another viewer cannot release its hold. A stale epoch or ended Run is refused before mutation. Automation remains blocked until the native applied ACK. Interrupted delivery returns unknown with its canonical Event ID and must not be retried automatically.
bctrl browsers control take
Give a current input-enabled viewer human control of the Browser. The viewer credential must belong to this Browser and current Run, and its parent View must still permit input. The hold ends with that viewer. The result names the canonical control Event; an unconfirmed native ACK returns unknown. Reusing the same Idempotency-Key never repeats the transition.
bctrl browsers create
Create a reusable browser and durably request its first Run. Use wait to wait up to 60 seconds for startup; currentRun is null until a Run is admitted and connections appear after the browser starts.
bctrl browsers delete
Delete the browser configuration and saved state, cancelling queued starts and stopping its current Run. Retained Run records remain readable.
bctrl browsers fetch
Send an HTTP request from the browser itself: it carries the browser’s cookies, proxy and TLS/HTTP2 fingerprint and is not subject to CORS. The response body is returned base64 encoded up to maxBytes (truncated is true beyond it). Human control blocks it; the Run’s Events record the URL without its query, the status and the byte count. An interrupted request returns unknown and must not be repeated automatically.
bctrl browsers fetchStream
Send an HTTP request from the browser itself, like fetch, and stream the response body back as it arrives, of any size and with bounded memory at every hop; a slow reader slows the upstream read. The upstream status is in BCTRL-Fetch-Status and its headers (JSON) in BCTRL-Fetch-Headers. A failure before the first byte is an error response; a failure after it aborts the stream, and the Run’s completion Event records unknown. Human control blocks it.
bctrl browsers files delete
Delete a file or directory of the current Browser Run; a non-empty directory needs recursive. Top-level directories and /files cannot be deleted. An interrupted deletion returns unknown.
bctrl browsers files download
Download one file of the current Browser Run (at most 1 GiB) as bytes. Headers carry its size and SHA-256.
bctrl browsers files list
List a directory of the current Browser Run. The top level holds /downloads, /files (the Run’s Space files, read only) and /workspace; nothing else of the machine is reachable. Pages are ordered by name and a cursor belongs to its Run.
bctrl browsers files move
Move or rename a file or directory of the current Browser Run within /downloads and /workspace. Set overwrite to replace the destination. An interrupted move returns unknown.
bctrl browsers files upload
Upload one file into /downloads or /workspace of the current Browser Run from multipart field file (at most 25 MiB). The file is written atomically; set overwrite to replace an existing file and createParents to create missing directories. An interrupted upload returns unknown.
bctrl browsers get
Read a browser and its current Run. Use wait to wait for an accepted start or stop. Saved state remains private to the browser and is restored on its next Run.
bctrl browsers list
List browser resources visible in the selected Space. A browser is running while it has a current Run and idle otherwise. Responses include the current Run and its connections when available.
bctrl browsers pages activate
Bring one page of the current Browser Run to the front. Activation is confirmed by the browser, never assumed. Human control blocks automation; an interrupted action returns unknown.
bctrl browsers pages close
Close one page of the current Browser Run. Human control blocks automation. An interrupted action returns unknown and must not be repeated automatically.
bctrl browsers pages get
Read one open page of the current Browser Run: its URL, title and whether it is active. The result carries its canonical Event ID.
bctrl browsers pages list
List the open pages of the current Browser Run, ordered by Page ID. A cursor belongs to the Run that produced it. The result carries its canonical Event ID; interrupted execution returns unknown.
bctrl browsers pages navigate
Navigate one page of the current Browser Run to an HTTP(S) URL and wait up to timeoutMs for its document. Human control blocks automation. An interrupted navigation returns unknown and must not be repeated automatically.
bctrl browsers pages open
Open a new page in the current Browser Run at an HTTP(S) URL or about:blank, activated by default. Human control blocks automation. An interrupted action returns unknown and must not be repeated automatically.
bctrl browsers pages pdf
Print one page of the current Browser Run to PDF. The document is returned base64 encoded. Interrupted execution returns unknown with null data.
bctrl browsers pages screenshot
Capture one page of the current Browser Run as PNG or JPEG, optionally the full page. The image is returned base64 encoded. Interrupted execution returns unknown with null data.
bctrl browsers recording get
Read capture and MP4 export progress for the current Browser Run. Completed recordings are read through the historical Run recording routes. A succeeded recording includes a direct standalone MP4 URL, expiry, SHA-256 and byte size. Partial capture is reported explicitly. Download URLs expire within five minutes and never outlive a View.
bctrl browsers runs list
List the retained Runs belonging to this browser, including ended and failed Runs, using cursor pagination.
bctrl browsers start
Durably request a new Run of this browser, restoring its saved state. If a previous Run is stopping or saving, startup waits for it. An existing current Run is returned without starting another browser.
bctrl browsers stop
Request the current Run to stop. State saving continues in the background after the browser exits. Set discardState to erase saved state and skip saving this Run. Use wait to wait for the requested stop.
bctrl browsers update
Update configuration used by the next Run. Changing stealth or viewport requires an idle browser without saved state or a queued start; stop with discardState first.