---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/commands
markdown_url: https://steel.dev/docs/reference/commands.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Commands reference
description: Look up every command that the Commands API accepts, from navigate and snapshot to click, fill, and wait, with its fields and results.
summary: Look up every command that the Commands API accepts, from navigate and snapshot to click, fill, and wait, with its fields and results.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/cli.md
  - https://steel.dev/docs/reference/mcp-tools.md
  - https://steel.dev/docs/reference/proxy-locations.md
  - https://steel.dev/docs/reference/signals.md
  - https://steel.dev/docs/reference/errors.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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](https://steel.dev/docs/control/commands) shows how to use them, and the [Sessions API](https://steel.dev/docs/reference/api/sessions) 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](https://steel.dev/docs/reference/commands#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.id`. 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](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/reference/errors). |

## Commands

Each command is an object. Its `command` field holds the command's name. Many commands take `target`, `frame` and `expect`, which [Targets](https://steel.dev/docs/reference/commands#targets) explains, and `tab`, which [Tabs](https://steel.dev/docs/reference/commands#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`](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/reference/api/sessions#upload-a-file-to-a-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](https://steel.dev/docs/reference/cli) and the [MCP server](https://steel.dev/docs/reference/mcp-tools) 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`](https://steel.dev/docs/reference/commands#navigate) | `steel browser navigate` | `navigate` |
| [`back`](https://steel.dev/docs/reference/commands#back) | `steel browser back` | `navigate` with `action: "back"` |
| [`forward`](https://steel.dev/docs/reference/commands#forward) | `steel browser forward` | `navigate` with `action: "forward"` |
| [`reload`](https://steel.dev/docs/reference/commands#reload) | `steel browser reload` | `navigate` with `action: "reload"` |
| [`snapshot`](https://steel.dev/docs/reference/commands#snapshot) | `steel browser snapshot` | `snapshot` |
| [`click`](https://steel.dev/docs/reference/commands#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`](https://steel.dev/docs/reference/commands#hover) | `steel browser hover` | `hover` |
| [`focus`](https://steel.dev/docs/reference/commands#focus) | `steel browser focus` | None |
| [`type`](https://steel.dev/docs/reference/commands#type) | `steel browser type` | `type` |
| [`fill`](https://steel.dev/docs/reference/commands#fill) | `steel browser fill`, and `steel browser clear`, which fills `""` | `fill`, which takes several fields |
| [`press`](https://steel.dev/docs/reference/commands#press) | `steel browser press`, and `steel browser selectall`, which presses `Control+a` | `press_key` |
| [`keydown`](https://steel.dev/docs/reference/commands#keydown) | `steel browser keydown` | None |
| [`keyup`](https://steel.dev/docs/reference/commands#keyup) | `steel browser keyup` | None |
| [`mouse`](https://steel.dev/docs/reference/commands#mouse) | `steel browser mouse` | None |
| [`select`](https://steel.dev/docs/reference/commands#select) | `steel browser select` | `select_option` |
| [`check`](https://steel.dev/docs/reference/commands#check) | `steel browser check` | `check` |
| [`uncheck`](https://steel.dev/docs/reference/commands#uncheck) | `steel browser uncheck` | `check` with `checked: false` |
| [`upload`](https://steel.dev/docs/reference/commands#upload) | `steel browser upload` | None |
| [`drag`](https://steel.dev/docs/reference/commands#drag) | `steel browser drag` | `drag` |
| [`get`](https://steel.dev/docs/reference/commands#get) | `steel browser get`, and `steel browser content` for the page's HTML | `get` |
| [`is`](https://steel.dev/docs/reference/commands#is) | `steel browser is` | None |
| [`wait`](https://steel.dev/docs/reference/commands#wait) | `steel browser wait` | `wait` |
| [`screenshot`](https://steel.dev/docs/reference/commands#screenshot) | `steel browser screenshot` | `screenshot` |
| [`eval`](https://steel.dev/docs/reference/commands#eval) | `steel browser eval` | `eval` |
| [`pdf`](https://steel.dev/docs/reference/commands#pdf) | `steel browser pdf` | None |
| [`scroll`](https://steel.dev/docs/reference/commands#scroll) | `steel browser scroll` | `scroll` |
| [`find`](https://steel.dev/docs/reference/commands#find) | `steel browser find` | `find` |
| [`tab`](https://steel.dev/docs/reference/commands#tab) | `steel browser tab` | `tab` |

The CLI and the MCP server also wait for and stop [executions](https://steel.dev/docs/reference/commands#executions):

| Endpoint | Steel CLI | MCP tool |
| - | - | - |
| `GET /v1/sessions/{sessionId}/commands/executions/{executionId}` | `steel browser status` | `status` |
| `POST /v1/sessions/{sessionId}/commands/executions/{executionId}/cancel` | `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`, 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`.

| 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`.

```json
{
  "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`](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/observability/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](https://steel.dev/docs/reference/errors#commands-api-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 /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}/cancel` | 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](https://steel.dev/docs/reference/commands#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](https://steel.dev/docs/reference/errors#error-response) instead. A command that fails has an `error` in its result, with `code`, `message`, and sometimes `reason`. [Errors](https://steel.dev/docs/reference/errors) lists both kinds of codes.
