Commands reference
A request to POST /v1/sessions/{sessionId}/commands runs commands such as navigate, snapshot, click and fill in a session. Each command takes its own fields and returns its own result. Commands shows how to use them, and the Sessions API reference has the endpoint.
Request
| Field | Type | Required | Description |
|---|---|---|---|
after | string | No | The next value from your last response. A retry with the same after and commands runs only once. |
commands | command, or array of commands | Yes | One command, or an array of 1 to 50. They run in order and stop at the first failure. Commands that already ran are not undone. |
observe | object | No | Returns a snapshot, or a diff against the last one, after the commands. |
observe has these fields:
| Field | Type | Required | Description |
|---|---|---|---|
base | string | No | A snapshot ID to diff against. |
compact | boolean | No | Only lines with refs or values, and their ancestors. |
depth | integer | No | Only lines up to this depth. At least 0. |
interactive | boolean | No | Only lines with refs. |
mode | snapshot or diff | Yes | snapshot returns a new snapshot of the tab. diff returns a diff against the tab's last snapshot, or against base. |
tab | string | No | A tab ID such as t2. |
The request takes one optional header:
| Header | Description |
|---|---|
Idempotency-Key | A random value of 1 to 255 characters. A retry with the same key returns the stored result. See Retries. |
Response
A run returns 200 even when a command fails. The error is then in results.
| Field | Type | Description |
|---|---|---|
id | string | The ID of this execution, such as x-1. The same as execution.. Use it to get or cancel the execution. |
page | object or null | The tab the execution used: tab, url and title. |
execution | object | The execution. See the next table. |
results | array | One result for each command that has finished. |
next | string | Send it as after in the next request. |
epoch | integer | A count of the changes to the session. It goes up by one when an execution changes the page, or may have changed it, and when the browser restarts. The SDK types leave it out. |
observe | object | The page after the commands, when the request has observe. |
dialog | object | A dialog that is open on the tab and blocks it until it closes. See Dialogs. |
epochChanged | boolean | Present when the request had after. true when another execution or a browser restart changed the session after that next was issued. Input from CDP clients or the live view does not count. |
bodyExpired | boolean | true when the response replays a stored result whose large parts, such as snapshot text, have expired. |
execution has these fields:
| Field | Type | Description |
|---|---|---|
id | string | The execution ID. |
state | running, completed, failed, cancelled, or timeout | The execution's state. Executions says what each state means. |
effect | none, applied, or unknown | What happened to the page: nothing, a change, or a possible change. |
replayed | boolean | true when the response is the stored result of an earlier request. |
ran | integer | The number of commands that started. |
error | object | The error, when the execution ended early. |
observe in the response has these fields:
| Field | Type | Description |
|---|---|---|
snapshotId | string | The new snapshot's ID. |
snapshot | string | The snapshot, for mode: "snapshot". |
diff | string | The diff, for mode: "diff". |
base | string | The snapshot ID that the diff compares against. |
additions | integer | Lines that the diff adds. |
removals | integer | Lines that the diff removes. |
full | boolean | true when there was no usable base, so the response has the full snapshot. |
error | object | The error, when Steel could not observe the page. |
The sections below list the result fields of each command. Every item of results also has these fields:
| Field | Type | Description |
|---|---|---|
command | string | The command's name. |
ok | boolean | true when the command succeeded. |
effect | none, applied, or unknown | What the command did to the page. |
error | object | code, message, and sometimes reason, when the command failed. See Errors. |
Commands
Each command is an object. Its command field holds the command's name. Many commands take target, frame and expect, which Targets explains, and tab, which Tabs explains.
navigate, back, forward, reload, and tab with action: "new" and a url wait up to 15 seconds for the page to load. When the page's DOM has loaded by then but the page is still loading, for example because an image is slow, the command succeeds with loading: true. When the DOM has not loaded, the command fails with timeout.
An input command such as click or press waits up to 15 seconds for the new page's DOM when it starts a navigation. When the page is still loading after that, the result has loading: true. In both cases, a wait with load: "load" waits for the page.
When an input command opens tabs, for example through a link with target="_blank", its result lists their IDs in opened, such as ["t2"]. A tab that opens after the command returns, for example from a timer, is not listed. The tab command with action: "list" shows it.
navigate
Opens a URL in the tab. Only http, https, and about:blank work. A URL without a scheme gets https://. It waits up to 15 seconds for the page to load.
| Field | Type | Required | Description |
|---|---|---|---|
tab | string | No | A tab ID such as t2. |
url | string | Yes | The URL to open. |
Result: url, a string, and loading.
back
Goes back one history entry.
| Field | Type | Required | Description |
|---|---|---|---|
tab | string | No | A tab ID such as t2. |
Result: navigated, a boolean that is false when there was no history entry, url, and loading.
forward
Goes forward one history entry.
| Field | Type | Required | Description |
|---|---|---|---|
tab | string | No | A tab ID such as t2. |
Result: navigated, a boolean that is false when there was no history entry, url, and loading.
reload
Reloads the tab.
| Field | Type | Required | Description |
|---|---|---|---|
tab | string | No | A tab ID such as t2. |
Result: url, a string, and loading.
snapshot
Returns the page's accessibility tree, with a ref for each element that you can act on or point to.
| Field | Type | Required | Description |
|---|---|---|---|
compact | boolean | No | Only lines with refs or values, and their ancestors. |
depth | integer | No | Only lines up to this depth. At least 0. |
interactive | boolean | No | Only lines with refs. |
tab | string | No | A tab ID such as t2. |
Result: snapshot, the tree as text, and snapshotId.
click
Clicks the element with the mouse. It scrolls the element into view first, and fails with not_actionable when something covers the element. For a double click, set clicks to 2.
| Field | Type | Required | Description |
|---|---|---|---|
button | left, right, or middle | No | The mouse button. left by default. |
clicks | integer | No | The number of clicks, from 1 to 3. 2 makes a double click, and 3 a triple click. 1 by default. |
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
Result: dialog, a dialog that the command opened, loading, and opened.
hover
Moves the mouse onto the element. It scrolls the element into view first.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
Result: dialog.
focus
Focuses the element.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
Result: no fields of its own.
type
Types text one key press at a time, after the current content.
| Field | Type | Required | Description |
|---|---|---|---|
clear | boolean | No | Replace the current content. |
delay | integer | No | Milliseconds to wait between key presses, from 0 to 1000. |
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
text | string | Yes | The text to type. |
Result: dialog, loading, and opened.
fill
Replaces a field's content in one step, without key presses. Date and time inputs take values such as 2025-01-31.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The field. |
value | string | Yes | The new content. |
Result: dialog, loading, and opened.
press
Presses a key, such as Enter, or a combination, such as Control+a. Key names follow the US keyboard layout. On a tab with an open dialog, Enter without target accepts the dialog, and Escape dismisses it. See Dialogs.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
key | string | Yes | The key or combination. |
tab | string | No | A tab ID such as t2. |
target | target | No | The element to press the key on. Without it, the key goes to the focused element. |
Result: dialog, loading, and opened.
keydown
Holds a key down until its keyup. A held modifier key applies to later input on the tab.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The key, such as Shift. |
tab | string | No | A tab ID such as t2. |
Result: dialog, loading, and opened.
keyup
Lets go of a key held with keydown.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The key, such as Shift. |
tab | string | No | A tab ID such as t2. |
Result: dialog, loading, and opened.
mouse
Sends mouse input at a point, for pages without useful elements, such as a canvas. x and y are CSS pixels of the visible part of the page.
| Field | Type | Required | Description |
|---|---|---|---|
action | move, down, up, click, or wheel | Yes | The mouse action. |
button | left, right, or middle | No | The mouse button. |
clicks | integer | No | The number of clicks, from 1 to 3. |
deltaX | number | No | The horizontal wheel movement. |
deltaY | number | No | The vertical wheel movement. |
tab | string | No | A tab ID such as t2. |
x | number | No | The horizontal position. Required for move, click and wheel. Send x and y together. |
y | number | No | The vertical position. Required for move, click and wheel. Send x and y together. |
Result: dialog, loading, and opened.
select
Selects options in a select element. It matches each value against the option values first, then against the option labels.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The select element. |
values | string, or array of strings | Yes | The options to select. |
Result: selected, the values of the selected options, dialog, loading, and opened.
check
Checks a checkbox, radio button, switch, or toggle button.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
Result: checked, a boolean, dialog, loading, and opened.
upload
Sets the files of a file input. The files must be in the session's files first, so upload them to the session. Then pass their names.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
files | string, or array of strings | Yes | The file names. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The file input. |
Result: files, an array of strings, dialog, loading, and opened.
drag
Drags one element onto another with the mouse. HTML5 drag and drop works.
| Field | Type | Required | Description |
|---|---|---|---|
frame | frame | No | The iframe to look in. |
source | target | Yes | The element to drag. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element to drop it on. |
Result: dialog, loading, and opened.
uncheck
Unchecks a checkbox, switch, or toggle button.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
Result: checked, a boolean, dialog, loading, and opened.
get
Reads something from the page or from an element.
| Field | Type | Required | Description |
|---|---|---|---|
attribute | string | No | The attribute to read. Required with what: "attr". |
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | No | The element. Required for every what except markdown, title and url, which read the page without it. count takes a CSS selector or a locator, not a ref. |
what | text, html, markdown, value, attr, title, url, count, box, or locator | Yes | What to read. See the next table. |
Result: what, value, and masked. what repeats what the command read, so the result alone tells the type of value. masked is true when the value is a secret and is left out.
what | value holds |
|---|---|
text | The text that a person can see, as a string. |
html | The HTML, as a string. |
markdown | The main content of the page as Markdown. With target, all of that element. |
value | A field's value, as a string. |
attr | The attribute named in attribute, as a string. |
title | The page title, as a string. |
url | The page URL, as a string. |
count | The number of elements that match target. |
box | { x, y, width, height } of the element in CSS pixels of the visible part of the page, or null. |
locator | A list of locators that find the element again in a later session, best first. |
is
Checks an element's state.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | The element. |
what | visible, enabled, or checked | Yes | The state to check. |
Result: value, a boolean.
wait
Waits for an element, text, a URL, a load state, a download, or a fixed time. Give exactly one condition. A request with two conditions fails with 400 before any command runs.
| Field | Type | Required | Description |
|---|---|---|---|
download | true | No | Waits for the next download to finish. |
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
load | load, domcontentloaded, or networkidle | No | Waits for this load state. |
ms | integer | No | Waits this many milliseconds, from 0 to 30000. |
state | visible, hidden, attached, or detached | No | The state to wait for, with target. visible by default. |
tab | string | No | A tab ID such as t2. |
target | target | No | Waits for this element. |
text | string | No | Waits for this text on the page. |
timeout | integer | No | Milliseconds, from 0 to 50000. 10000 by default. |
url | string | No | Waits until the tab's URL contains this text. With * in it, the whole URL must match the pattern, and * matches any characters. |
Result: waited, the condition that ended the wait (ms, target, text, url, load, or download). For a download, also file, the downloaded file's name, and bytes, its size.
screenshot
Captures the page or an element as base64 data.
| Field | Type | Required | Description |
|---|---|---|---|
expect | object | No | Fails the command when the element does not have this role or name. |
format | png, jpeg, or webp | No | The image format. png by default. |
frame | frame | No | The iframe to look in. |
fullPage | boolean | No | Capture the whole page, not only the visible part. |
quality | integer | No | The image quality, from 0 to 100. For jpeg and webp only. |
tab | string | No | A tab ID such as t2. |
target | target | No | The element to capture. |
Result: data, the image as base64, and format.
eval
Runs JavaScript in the page and returns the result as JSON. It waits for a promise to settle, and fails with script_error when the script throws.
| Field | Type | Required | Description |
|---|---|---|---|
script | string | Yes | The JavaScript to run. |
tab | string | No | A tab ID such as t2. |
timeout | integer | No | Milliseconds, from 0 to 50000. 10000 by default. |
Result: value, the script's result as JSON, dialog, loading, and opened.
pdf
Prints the page to a PDF as base64 data. It works in headful and headless sessions.
| Field | Type | Required | Description |
|---|---|---|---|
landscape | boolean | No | Use the landscape orientation. |
printBackground | boolean | No | Print the background graphics. |
tab | string | No | A tab ID such as t2. |
Result: data, the PDF as base64, and format, which is pdf.
scroll
Scrolls the page, or an element when target is set.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | No | Pixels, at least 1. 300 by default. |
direction | up, down, left, or right | No | The direction to scroll. down by default. |
expect | object | No | Fails the command when the element does not have this role or name. |
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | No | The element whose content to scroll, such as a list or a panel. |
Result: x and y, the new scroll position, and moved, a boolean.
find
Finds elements and returns refs for up to 50 matches. With nth in the locator, it returns that one match.
| Field | Type | Required | Description |
|---|---|---|---|
frame | frame | No | The iframe to look in. |
tab | string | No | A tab ID such as t2. |
target | target | Yes | A CSS selector or a locator, not a ref. |
Result: count, the number of matches, and matches, an array of objects with ref, role and name.
tab
Lists, opens, or closes tabs. The last tab cannot be closed.
| Field | Type | Required | Description |
|---|---|---|---|
action | list, new, or close | Yes | What to do. |
tab | string | No | The tab to close. |
url | string | No | The URL that a new tab opens. |
Result: tab, the tab that the command opened or closed, and loading for a new tab. For list, the result is tabs instead, an array of objects with tab, url and title.
Names in the CLI and the MCP server
The Steel CLI and the MCP server send these commands under their own names. This table maps each command to its CLI command and its MCP tool. None means that the interface cannot send the command.
| Command | Steel CLI | MCP tool |
|---|---|---|
navigate | steel browser navigate | navigate |
back | steel browser back | navigate with action: "back" |
forward | steel browser forward | navigate with action: "forward" |
reload | steel browser reload | navigate with action: "reload" |
snapshot | steel browser snapshot | snapshot |
click | steel browser click. For a double-click, steel browser dblclick or click --count 2, which send the older dblclick form. | click, with double for a double-click |
hover | steel browser hover | hover |
focus | steel browser focus | None |
type | steel browser type | type |
fill | steel browser fill, and steel browser clear, which fills "" | fill, which takes several fields |
press | steel browser press, and steel browser selectall, which presses Control+a | press_key |
keydown | steel browser keydown | None |
keyup | steel browser keyup | None |
mouse | steel browser mouse | None |
select | steel browser select | select_option |
check | steel browser check | check |
uncheck | steel browser uncheck | check with checked: false |
upload | steel browser upload | None |
drag | steel browser drag | drag |
get | steel browser get, and steel browser content for the page's HTML | get |
is | steel browser is | None |
wait | steel browser wait | wait |
screenshot | steel browser screenshot | screenshot |
eval | steel browser eval | eval |
pdf | steel browser pdf | None |
scroll | steel browser scroll | scroll |
find | steel browser find | find |
tab | steel browser tab | tab |
The CLI and the MCP server also wait for and stop executions:
| Endpoint | Steel CLI | MCP tool |
|---|---|---|
GET / | steel browser status | status |
POST / | steel browser cancel | cancel |
steel browser batch sends several commands in one request. The MCP server has no tool that takes a list of commands.
Targets
target and source take one of these:
- A ref from a snapshot, such as
e12, orref=e12as the snapshot prints it. A ref knows its tab, so a command on a ref does not needtab. - A CSS selector, such as
#remember-me. - A locator object.
A locator sets exactly one of role, text, label, placeholder, alt, title, testid and css.
| Field | Type | Description |
|---|---|---|
alt | string | Image alt text. |
css | string | A CSS selector. |
exact | boolean | Match the whole text. Text matches a case-insensitive substring by default. testid always matches exactly. |
label | string | A form field's label. |
name | string | The accessible name. Works only with role. |
nth | integer | Picks one of several matches. Negative values count from the end. |
placeholder | string | Placeholder text. |
role | string | The accessibility role. |
testid | string | The data-testid attribute. |
text | string | Text in the element, hidden or not. When an element and its child both contain the text, only the child matches. |
title | string | The title attribute. |
When a locator finds several elements and only one of them is visible, the command uses that one. Otherwise, it fails with the reason ambiguous. Set nth to pick one.
Frames
frame names the iframe to look in, in the same forms as a target. For nested iframes, pass an array of up to 8 targets, from the outside in. A ref already knows its frame, so a command whose target is a ref takes no frame.
{
"command": "click",
"target": { "role": "button", "name": "Pay", "exact": true },
"frame": ["#checkout", { "title": "Payment" }],
"expect": { "role": "button" }
}Expectations
expect makes the command fail when the element does not have this role or this name. Use it to check that a ref still points at the element that you meant.
Tabs
Each tab in a session has an ID, such as t1 or t2. The tab command lists, opens and closes tabs.
A command that does not act on a ref, such as navigate or a click on a CSS selector, works on the tab in its tab field. With one tab open, it can leave tab out. When more than one tab is open and the command names none, it fails with tab_required.
Dialogs
A JavaScript dialog, such as an alert or a confirm, blocks its tab until it closes. Steel never answers a dialog on its own. Until the dialog closes, commands on its tab fail with dialog_pending, except the two key presses that answer it:
{ "command": "press", "key": "Enter" }accepts the dialog. A prompt gets its default text.{ "command": "press", "key": "Escape" }dismisses the dialog.
Send the press without target and without modifier keys, and pass tab when more than one tab is open. Any other key fails with dialog_pending. The press is a command like any other: after and Idempotency-Key keep a retry from pressing the key twice, and its effect is applied once the dialog has closed. When the page opens another dialog right away, the result shows it in dialog.
A press reaches the dialog only while the dialog is open. When the dialog has already closed, for example because a person answered it in the live view, the key goes to the page like any other press. When the dialog closes while the press is on its way, the press fails with not_actionable and the reason dialog_closed, and no key goes to the page. When the dialog does not close, the press fails with dialog_pending and the reason unanswered.
When a dialog opens partway through a command, for example while type types, the command fails with dialog_pending and does not go on after the dialog closes. Answer the dialog, then send the command again. A person can also answer a dialog in the live view, and closing the tab with the tab command closes its dialog too.
A response shows an open dialog in dialog, with these fields:
| Field | Type | Description |
|---|---|---|
id | string | The dialog ID. |
tab | string | The tab that the dialog blocks. |
type | alert, confirm, prompt, or beforeunload | The kind of dialog. |
message | string | The dialog's text. |
defaultPrompt | string | A prompt's default answer. |
Executions
Each request runs as one execution. A session runs one execution at a time, and later ones wait in a queue. A response waits up to 20 seconds for its execution. If the execution is still going, the response has state: "running".
An execution is in one of these states:
| State | Meaning |
|---|---|
running | It started and has not ended. |
completed | Every command succeeded. |
failed | A command failed, and the execution stopped there. |
cancelled | You cancelled it. |
timeout | It ran longer than 60 seconds. |
An execution that waits in the queue has no state that you can see. When it cannot start within 20 seconds, it does not run, and its request gets no execution back. The request fails with 429 and the code expired, as Errors shows. Send it again.
These endpoints wait for an execution or stop it. Each returns the same response as a run.
| Endpoint | Description |
|---|---|
GET / | Waits up to 20 seconds for the execution to finish, and returns it. |
POST / | Stops the execution. The running command stops before its next input. Commands that already ran are not undone. |
A cancel also stops a page load, and the tab stays open. When the running command has not stopped 2 seconds after a cancel, or 15 seconds after a timeout, Steel stops the page's scripts. If the command had already sent input to the page, Steel then closes its tab, and as a last resort ends the session. Before Steel closes the last open tab, it opens a new one. Steel stops waiting for a command that had not sent input yet, such as snapshot, and its tab stays open.
Retries
To make a request safe to retry, send it with an Idempotency-Key header that holds a random value. A retry with the same key returns the stored result, with execution.replayed set to true, and does not run the commands again. A key that you reuse with different commands fails with 422 and the code key_conflict.
after gives a retry the same protection. A retry with the same after and the same commands runs only once, even when its key changed.
Steel keeps the stored result of a request with a key for at least one hour after the execution ends. It keeps large parts of the result, such as snapshot text and screenshot data, for 10 minutes. A replay after that returns the rest of the result, with bodyExpired: true.
Older forms
Steel still accepts these older forms of a request for now, and runs them as the newer form. Each response to a request in an older form has the header x-steel-deprecated, which names the forms that it used. Move to the newer form, because the older ones will stop working.
| Older form | Newer form |
|---|---|
{ "command": "dblclick", "target": "e5" } | { "command": "click", "target": "e5", "clicks": 2 }. The result names click. |
A ref written as @e12 | e12 or ref=e12 |
observe with mode: "none" | No observe |
The dialog command no longer works. It fails with 400 and the code invalid_request. Answer a dialog with press, as Dialogs shows.
Limits
| Limit | Value |
|---|---|
| Commands in one request | 50 |
| Wait for a response | 20 seconds, then state: "running" |
| Run time of one execution | 60 seconds |
| Executions waiting in one session | 16 |
Page load for navigate, back, forward, reload, and a new tab | 15 seconds |
wait and eval timeout | 10 seconds by default, 50 seconds at most |
next, sent as after | 1 hour |
Stored result of a request with an Idempotency-Key | At least 1 hour after the execution ends |
| Large parts of a result, such as snapshot text and screenshot data | 10 minutes |
Error codes
A request that fails as a whole has no execution. Its body is { "error": { "code": ..., "message": ... } }. A 401 or 403 has the shape in Error response instead. A command that fails has an error in its result, with code, message, and sometimes reason. Errors lists both kinds of codes.