Commands
Commands drive a session's browser one step at a time. They read the page as a snapshot, act on an element by its ref, and return what changed. Commands are built for agents that drive a browser interactively: a model reads the page, picks the next step, and reads the result. The steel browser commands of the Steel CLI and the page tools of the MCP server run on Commands. For a script that runs the same steps every time, use Playwright or Puppeteer over CDP instead.
This page uses Commands through the Steel CLI. To call them from your own agent harness, see Build your own agent harness.
Before you begin
Install the Steel CLI and sign in. CLI has the steps.
The CLI examples drive a public TodoMVC demo app. They use the session named default, which the first command starts. The session ends by itself when it sits idle or reaches its timeout, as Set timeouts shows. When you are done, run steel browser stop to release the session.
Read the page
Open the page, and take a snapshot of it:
steel browser open https://demo.playwright.dev/todomvc
steel browser snapshot -isnapshot -i prints the elements that have a ref:
- link "real TodoMVC app." [ref=e1]
- heading "todos" [level=1, ref=e2]
- textbox "What needs to be done?" [ref=e3]
- link "Remo H. Jansen" [ref=e4]
- link "TodoMVC" [ref=e5]Each line is one element: its role, its name in quotes, its states in brackets, and its ref. A ref, such as e3, is a short name for one element on the page. The agent reads the snapshot, picks a ref, and passes it to the next command. Without -i, the snapshot also has the text and the structure of the page. Snapshots and refs explains both.
Act on a ref
Pass a ref to a command that acts on an element. These commands type a todo into the field e3, and press Enter to add it:
steel browser fill e3 "Buy milk"
steel browser press Enterfill replaces the value of the field. press presses a key in the element that has focus, here the same field. A command that acts prints nothing when it succeeds.
A command that takes a ref also takes a CSS selector. Other commands act on an element the same way, such as click, check, select and upload. CLI commands lists them all.
A ref stays the same while its element is on the page. When the element leaves the page, a command on its ref fails with stale_ref. Take a new snapshot, and pick the element again.
Observe what changed
To see the page after an action, take a new snapshot:
steel browser snapshot -i- link "real TodoMVC app." [ref=e1]
- heading "todos" [level=1, ref=e2]
- textbox "What needs to be done?" [ref=e3]
- checkbox "❯Mark all as complete" [checked=false, ref=e6]
- checkbox "Toggle Todo" [checked=false, ref=e7]
- link "All" [ref=e8]
- link "Active" [ref=e9]
- link "Completed" [ref=e10]
- link "Remo H. Jansen" [ref=e4]
- link "TodoMVC" [ref=e5]The page now has a checkbox for the todo, e7, and links that filter the list. A full snapshot after each step is long. Instead, add --diff to the command that acts. It prints only the lines that changed since your last snapshot or diff. The diff keeps the options of that snapshot, such as -i. Mark the todo as done:
steel browser click e7 --diff--- before
+++ after
@@ -1,10 +1,12 @@
- link "real TodoMVC app." [ref=e1]
- heading "todos" [level=1, ref=e2]
- textbox "What needs to be done?" [ref=e3]
-- checkbox "❯Mark all as complete" [checked=false, ref=e6]
-- checkbox "Toggle Todo" [checked=false, ref=e7]
+- checkbox "❯Mark all as complete" [checked=true, ref=e6]
+- checkbox "Toggle Todo" [checked=true, ref=e7]
+- button "Delete" [ref=e12]
- link "All" [ref=e8]
- link "Active" [ref=e9]
- link "Completed" [ref=e10]
+- button "Clear completed" [ref=e11]
- link "Remo H. Jansen" [ref=e4]
- link "TodoMVC" [ref=e5]A line that starts with - is gone, and a line that starts with + is new. A change of state, such as checked, shows as both. The other lines are context. When the page did not change, the CLI prints No changes. When Steel has no earlier snapshot to compare with, it returns the full snapshot, and the CLI prints that instead.
--diff adds observe to the request, which Build your own agent harness explains.
Run several commands in one request
Each steel browser command sends one request to Steel. batch sends several commands in one request, so the agent waits for one round trip instead of several. Write each command as one string:
steel browser batch "fill e3 'Walk the dog'" "press Enter" "snapshot -i"The commands run in order and stop at the first one that fails. This batch adds a second todo, and prints the snapshot of its last command:
- link "real TodoMVC app." [ref=e1]
- heading "todos" [level=1, ref=e2]
- textbox "What needs to be done?" [ref=e3]
- checkbox "❯Mark all as complete" [checked=false, ref=e6]
- checkbox "Toggle Todo" [checked=true, ref=e7]
- button "Delete" [ref=e12]
- checkbox "Toggle Todo" [checked=false, ref=e13]
- link "All" [ref=e8]
- link "Active" [ref=e9]
- link "Completed" [ref=e10]
- button "Clear completed" [ref=e11]
- link "Remo H. Jansen" [ref=e4]
- link "TodoMVC" [ref=e5]A batch takes up to 50 commands. tab new, tab switch and tab close must run on their own. When a command fails, the commands before it are not undone.
Wait for the page
open waits up to 15 seconds for the page to load. When the page changes later, for example when it loads data, wait for what you expect to see:
steel browser wait --text "Walk the dog"wait takes one condition, such as --text, --selector with a ref or a CSS selector, --url, --load-state, or a time in milliseconds. It prints nothing when the condition is met. When the condition is not met within --timeout milliseconds, 30000 by default and 50000 at most, it fails with timeout. The CLI sends its own default, so it waits longer than a wait command that you send to the API without a timeout, which waits 10000:
steel browser wait --text "Buy bread" --timeout 3000Error: timeout: Waited 3 seconds for the condition, but it did not happen.A request to Steel waits up to 20 seconds for its commands. When they run longer, the CLI asks Steel again until they end, so a long wait prints its result as usual. Steel stops the commands of a request after 60 seconds.
Retry safely
A response can get lost after the browser ran the command, for example when the network drops. Running the command again must not repeat its action, such as a click. The CLI sends each command with a random Idempotency-Key, and with the next value of the last response as after. When Steel cannot reach the browser, or the session is busy, the CLI retries on its own with the same key.
When the CLI says that running the same command again is safe, run it again. Steel returns the stored result of the first run and runs nothing. CLI shows the note that the CLI prints then.
Build your own agent harness
The CLI and the MCP server send each step as one request to POST /v1/sessions/SESSION_ID/commands. To give your own agent a browser, send these requests from your harness, and pass what they return to your model. Create a session first, put its ID in SESSION_ID, and put your API key in STEEL_API_KEY. The SDKs send the same request with client.sessions.commands (client.Sessions.Commands in Go and client.sessions().commands in Rust). The examples below use cURL, so that you can see the request and its response.
This request opens a page, and asks for a snapshot of it with observe. "interactive": true keeps only the lines with refs, as -i does:
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"commands": [{ "command": "navigate", "url": "https://example.com" }],
"observe": { "mode": "snapshot", "interactive": true }
}'The response has the page that the commands used, one result for each command, and the snapshot:
{
"id": "x-23",
"next": "op_pesp7xzk60",
"epoch": 1,
"page": { "tab": "t202", "url": "https://example.com/", "title": "Example Domain" },
"execution": { "id": "x-23", "state": "completed", "effect": "applied", "replayed": false, "ran": 1 },
"results": [
{ "command": "navigate", "ok": true, "effect": "applied", "url": "https://example.com/" }
],
"observe": { "snapshotId": "s-1", "snapshot": "- link \"Learn more\" [ref=e1]" }
}Give observe.snapshot to your model, and keep next. The model answers with the ref of the element to act on, such as e1 for the link. Send the ref as the target of a command, and the last next as after:
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"after": "op_pesp7xzk60",
"commands": [{ "command": "click", "target": "e1" }]
}'{
"id": "x-24",
"next": "op_yjz18xxmlz",
"epoch": 2,
"epochChanged": false,
"page": { "tab": "t202", "url": "https://www.iana.org/help/example-domains", "title": "Example Domains" },
"execution": { "id": "x-24", "state": "completed", "effect": "applied", "replayed": false, "ran": 1 },
"results": [
{ "command": "click", "ok": true, "effect": "applied" }
]
}page shows that the click opened a new page. Add observe to the request, as in the first one, to get the new page in the same response. With "mode": "diff", you get only the lines that changed, as --diff prints them.
after tells Steel which state of the session your model saw. When another request changed the page after that next, or the browser restarted, the response has epochChanged: true. Input from a CDP client or from the live view does not count. Take a new snapshot before you act on old refs.
A command that fails does not fail the request. The response still has status 200, the command's result has ok: false and an error, and execution.state is failed. The commands after it do not run, and the commands before it are not undone.
When a command opens a new tab, its result lists the tab's ID in opened. When the page opens a JavaScript dialog, the response has dialog, and commands on that tab fail with dialog_pending until the dialog closes. To answer it, send press with no target: Enter accepts the dialog, and Escape dismisses it. Dialogs has the rules.
Each request runs as one execution, with an ID such as x-24. A session runs one execution at a time. A request waits up to 20 seconds for its execution. When the execution is still running, the response has execution.state set to running, and results has only the commands that have finished. This request waits 25 seconds, so its response comes after 20:
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"after": "op_yjz18xxmlz",
"commands": [{ "command": "wait", "ms": 25000 }]
}'{
"id": "x-25",
"next": "op_na7nyqacgw",
"epoch": 2,
"epochChanged": false,
"page": { "tab": "t202", "url": "https://www.iana.org/help/example-domains", "title": "Example Domains" },
"execution": { "id": "x-25", "state": "running", "effect": "none", "replayed": false, "ran": 1 },
"results": []
}Get the execution by its ID. Each call waits up to 20 seconds more for it to end, and returns the same fields:
curl https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-25 \
-H "steel-api-key: $STEEL_API_KEY"To stop an execution, send POST /v1/sessions/SESSION_ID/commands/executions/EXECUTION_ID/cancel. Steel stops an execution after 60 seconds. When a command does not stop, Steel can close its tab or end the session, as Executions explains.
To make a retry safe, send each request with an Idempotency-Key header that holds a random value, and send the same key when you retry it. A retry with the same key, or with the same after and the same commands, returns the stored result with execution.replayed set to true, and runs nothing. When you send the click request above again, the response is x-24 again, with "replayed": true.
Commands reference lists every command with its fields and results, and the limits. Run commands in the Sessions API has the endpoints, and Commands API errors has the errors of a request that fails as a whole.
Check that it worked
Open the live view URL that steel browser live prints. The page shows two todos: Buy milk is checked and Walk the dog is not, as the two Toggle Todo checkboxes of the last snapshot say. In your own harness, check each response: execution.state is completed, and each result has ok: true.