Skip to content

Commands reference

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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

FieldTypeRequiredDescription
afterstringNoThe next value from your last response. A retry with the same after and commands runs only once.
commandscommand, or array of commandsYesOne 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.
observeobjectNoReturns a snapshot, or a diff against the last one, after the commands.

observe has these fields:

FieldTypeRequiredDescription
basestringNoA snapshot ID to diff against.
compactbooleanNoOnly lines with refs or values, and their ancestors.
depthintegerNoOnly lines up to this depth. At least 0.
interactivebooleanNoOnly lines with refs.
modesnapshot or diffYessnapshot returns a new snapshot of the tab. diff returns a diff against the tab's last snapshot, or against base.
tabstringNoA tab ID such as t2.

The request takes one optional header:

HeaderDescription
Idempotency-KeyA 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.

FieldTypeDescription
idstringThe ID of this execution, such as x-1. The same as execution.id. Use it to get or cancel the execution.
pageobject or nullThe tab the execution used: tab, url and title.
executionobjectThe execution. See the next table.
resultsarrayOne result for each command that has finished.
nextstringSend it as after in the next request.
epochintegerA 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.
observeobjectThe page after the commands, when the request has observe.
dialogobjectA dialog that is open on the tab and blocks it until it closes. See Dialogs.
epochChangedbooleanPresent 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.
bodyExpiredbooleantrue when the response replays a stored result whose large parts, such as snapshot text, have expired.

execution has these fields:

FieldTypeDescription
idstringThe execution ID.
staterunning, completed, failed, cancelled, or timeoutThe execution's state. Executions says what each state means.
effectnone, applied, or unknownWhat happened to the page: nothing, a change, or a possible change.
replayedbooleantrue when the response is the stored result of an earlier request.
ranintegerThe number of commands that started.
errorobjectThe error, when the execution ended early.

observe in the response has these fields:

FieldTypeDescription
snapshotIdstringThe new snapshot's ID.
snapshotstringThe snapshot, for mode: "snapshot".
diffstringThe diff, for mode: "diff".
basestringThe snapshot ID that the diff compares against.
additionsintegerLines that the diff adds.
removalsintegerLines that the diff removes.
fullbooleantrue when there was no usable base, so the response has the full snapshot.
errorobjectThe 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:

FieldTypeDescription
commandstringThe command's name.
okbooleantrue when the command succeeded.
effectnone, applied, or unknownWhat the command did to the page.
errorobjectcode, 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.

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.

FieldTypeRequiredDescription
tabstringNoA tab ID such as t2.
urlstringYesThe URL to open.

Result: url, a string, and loading.

back

Goes back one history entry.

FieldTypeRequiredDescription
tabstringNoA 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.

FieldTypeRequiredDescription
tabstringNoA 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.

FieldTypeRequiredDescription
tabstringNoA 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.

FieldTypeRequiredDescription
compactbooleanNoOnly lines with refs or values, and their ancestors.
depthintegerNoOnly lines up to this depth. At least 0.
interactivebooleanNoOnly lines with refs.
tabstringNoA 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.

FieldTypeRequiredDescription
buttonleft, right, or middleNoThe mouse button. left by default.
clicksintegerNoThe number of clicks, from 1 to 3. 2 makes a double click, and 3 a triple click. 1 by default.
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe element.

Result: dialog.

focus

Focuses the element.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe element.

Result: no fields of its own.

type

Types text one key press at a time, after the current content.

FieldTypeRequiredDescription
clearbooleanNoReplace the current content.
delayintegerNoMilliseconds to wait between key presses, from 0 to 1000.
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe element.
textstringYesThe 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe field.
valuestringYesThe 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
keystringYesThe key or combination.
tabstringNoA tab ID such as t2.
targettargetNoThe 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.

FieldTypeRequiredDescription
keystringYesThe key, such as Shift.
tabstringNoA tab ID such as t2.

Result: dialog, loading, and opened.

keyup

Lets go of a key held with keydown.

FieldTypeRequiredDescription
keystringYesThe key, such as Shift.
tabstringNoA 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.

FieldTypeRequiredDescription
actionmove, down, up, click, or wheelYesThe mouse action.
buttonleft, right, or middleNoThe mouse button.
clicksintegerNoThe number of clicks, from 1 to 3.
deltaXnumberNoThe horizontal wheel movement.
deltaYnumberNoThe vertical wheel movement.
tabstringNoA tab ID such as t2.
xnumberNoThe horizontal position. Required for move, click and wheel. Send x and y together.
ynumberNoThe 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe select element.
valuesstring, or array of stringsYesThe 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
filesstring, or array of stringsYesThe file names.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe 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.

FieldTypeRequiredDescription
frameframeNoThe iframe to look in.
sourcetargetYesThe element to drag.
tabstringNoA tab ID such as t2.
targettargetYesThe element to drop it on.

Result: dialog, loading, and opened.

uncheck

Unchecks a checkbox, switch, or toggle button.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe element.

Result: checked, a boolean, dialog, loading, and opened.

get

Reads something from the page or from an element.

FieldTypeRequiredDescription
attributestringNoThe attribute to read. Required with what: "attr".
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetNoThe 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.
whattext, html, markdown, value, attr, title, url, count, box, or locatorYesWhat 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.

whatvalue holds
textThe text that a person can see, as a string.
htmlThe HTML, as a string.
markdownThe main content of the page as Markdown. With target, all of that element.
valueA field's value, as a string.
attrThe attribute named in attribute, as a string.
titleThe page title, as a string.
urlThe page URL, as a string.
countThe 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.
locatorA list of locators that find the element again in a later session, best first.

is

Checks an element's state.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesThe element.
whatvisible, enabled, or checkedYesThe 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.

FieldTypeRequiredDescription
downloadtrueNoWaits for the next download to finish.
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
loadload, domcontentloaded, or networkidleNoWaits for this load state.
msintegerNoWaits this many milliseconds, from 0 to 30000.
statevisible, hidden, attached, or detachedNoThe state to wait for, with target. visible by default.
tabstringNoA tab ID such as t2.
targettargetNoWaits for this element.
textstringNoWaits for this text on the page.
timeoutintegerNoMilliseconds, from 0 to 50000. 10000 by default.
urlstringNoWaits 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.

FieldTypeRequiredDescription
expectobjectNoFails the command when the element does not have this role or name.
formatpng, jpeg, or webpNoThe image format. png by default.
frameframeNoThe iframe to look in.
fullPagebooleanNoCapture the whole page, not only the visible part.
qualityintegerNoThe image quality, from 0 to 100. For jpeg and webp only.
tabstringNoA tab ID such as t2.
targettargetNoThe 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.

FieldTypeRequiredDescription
scriptstringYesThe JavaScript to run.
tabstringNoA tab ID such as t2.
timeoutintegerNoMilliseconds, 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.

FieldTypeRequiredDescription
landscapebooleanNoUse the landscape orientation.
printBackgroundbooleanNoPrint the background graphics.
tabstringNoA 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.

FieldTypeRequiredDescription
amountnumberNoPixels, at least 1. 300 by default.
directionup, down, left, or rightNoThe direction to scroll. down by default.
expectobjectNoFails the command when the element does not have this role or name.
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetNoThe 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.

FieldTypeRequiredDescription
frameframeNoThe iframe to look in.
tabstringNoA tab ID such as t2.
targettargetYesA 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.

FieldTypeRequiredDescription
actionlist, new, or closeYesWhat to do.
tabstringNoThe tab to close.
urlstringNoThe 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.

CommandSteel CLIMCP tool
navigatesteel browser navigatenavigate
backsteel browser backnavigate with action: "back"
forwardsteel browser forwardnavigate with action: "forward"
reloadsteel browser reloadnavigate with action: "reload"
snapshotsteel browser snapshotsnapshot
clicksteel 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
hoversteel browser hoverhover
focussteel browser focusNone
typesteel browser typetype
fillsteel browser fill, and steel browser clear, which fills ""fill, which takes several fields
presssteel browser press, and steel browser selectall, which presses Control+apress_key
keydownsteel browser keydownNone
keyupsteel browser keyupNone
mousesteel browser mouseNone
selectsteel browser selectselect_option
checksteel browser checkcheck
unchecksteel browser uncheckcheck with checked: false
uploadsteel browser uploadNone
dragsteel browser dragdrag
getsteel browser get, and steel browser content for the page's HTMLget
issteel browser isNone
waitsteel browser waitwait
screenshotsteel browser screenshotscreenshot
evalsteel browser evaleval
pdfsteel browser pdfNone
scrollsteel browser scrollscroll
findsteel browser findfind
tabsteel browser tabtab

The CLI and the MCP server also wait for and stop executions:

EndpointSteel CLIMCP tool
GET /v1/sessions/{sessionId}/commands/executions/{executionId}steel browser statusstatus
POST /v1/sessions/{sessionId}/commands/executions/{executionId}/cancelsteel browser cancelcancel

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, or ref=e12 as the snapshot prints it. A ref knows its tab, so a command on a ref does not need tab.
  • 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.

FieldTypeDescription
altstringImage alt text.
cssstringA CSS selector.
exactbooleanMatch the whole text. Text matches a case-insensitive substring by default. testid always matches exactly.
labelstringA form field's label.
namestringThe accessible name. Works only with role.
nthintegerPicks one of several matches. Negative values count from the end.
placeholderstringPlaceholder text.
rolestringThe accessibility role.
testidstringThe data-testid attribute.
textstringText in the element, hidden or not. When an element and its child both contain the text, only the child matches.
titlestringThe 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:

FieldTypeDescription
idstringThe dialog ID.
tabstringThe tab that the dialog blocks.
typealert, confirm, prompt, or beforeunloadThe kind of dialog.
messagestringThe dialog's text.
defaultPromptstringA 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:

StateMeaning
runningIt started and has not ended.
completedEvery command succeeded.
failedA command failed, and the execution stopped there.
cancelledYou cancelled it.
timeoutIt 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.

EndpointDescription
GET /v1/sessions/{sessionId}/commands/executions/{executionId}Waits up to 20 seconds for the execution to finish, and returns it.
POST /v1/sessions/{sessionId}/commands/executions/{executionId}/cancelStops 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 formNewer form
{ "command": "dblclick", "target": "e5" }{ "command": "click", "target": "e5", "clicks": 2 }. The result names click.
A ref written as @e12e12 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

LimitValue
Commands in one request50
Wait for a response20 seconds, then state: "running"
Run time of one execution60 seconds
Executions waiting in one session16
Page load for navigate, back, forward, reload, and a new tab15 seconds
wait and eval timeout10 seconds by default, 50 seconds at most
next, sent as after1 hour
Stored result of a request with an Idempotency-KeyAt least 1 hour after the execution ends
Large parts of a result, such as snapshot text and screenshot data10 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.