---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/cli
markdown_url: https://steel.dev/docs/reference/cli.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: CLI commands
description: Look up every command of the Steel CLI, with its flags and output.
summary: Look up every command of the Steel CLI, with its flags and output.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/mcp-tools.md
  - https://steel.dev/docs/reference/commands.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
---

# CLI commands

Each command of the Steel CLI 0.5.0, such as `steel scrape` or `steel sessions list`, takes its own arguments and flags. The page starts with `steel init`, `steel login` and `steel logout`, which set up the CLI. The other commands follow the order of `steel describe --all`. [CLI](https://steel.dev/docs/control/cli) shows the common tasks. For the version that you have installed, run `steel describe` with a command path, such as `steel describe browser click`, or add `--help` to any command.

## Global options

Every command accepts these options.

| Option | Type | Description |
| - | - | - |
| `--json` | boolean | Print all results as JSON, for automation. |
| `--local` | boolean | Use the local Steel runtime instead of Steel Cloud. |
| `--api-url` | string | The Steel API URL. It overrides `--local` and `STEEL_API_URL`. |
| `-h, --help` | | Print help for a command. |
| `-V, --version` | | Print the version of the Steel CLI. Only `steel` itself takes it, as `steel --version`. |

Every `steel browser` command also accepts these options:

| Option | Type | Description |
| - | - | - |
| `--session` | string | The named session to use, or a session ID. `default` when you leave it out. `--session-id` is an alias. |
| `--diff` | boolean | Print what the command changed on the page, as a diff against the last snapshot. |

## Environment variables

| Variable | Description |
| - | - |
| `STEEL_API_KEY` | The API key. It overrides the sign-in that `steel login` saved. |
| `STEEL_API_URL` | The Steel API URL, for Steel Cloud or a self-hosted instance. |
| `STEEL_WS_URL` | The WebSocket URL for `steel sessions logs --follow` and `steel sessions traces --follow`. |
| `STEEL_CONFIG_DIR` | The configuration directory. `~/.config/steel` by default. |
| `STEEL_TELEMETRY_HOST` | Overrides the host that receives telemetry. |
| `STEEL_TELEMETRY_DISABLED` | Set it to `1` or `true` to turn telemetry off. |
| `NO_COLOR` | Turns colored output off. |

## Output

Commands print text by default, even when you pipe them. `--json` prints the result as `{"success": true, "data": ...}`. `steel browser` commands print the result on standard output, and notes about dialogs, new tabs, downloads and retried requests on standard error.

`steel browser start` prints the session `id`, `mode`, `name`, `live_url`, `connect_url`, `expires_in` and `inactivity_timeout`. With `--json`, `data` has the keys `id`, `mode`, `name`, `liveUrl`, `connectUrl`, `remainingMs` and `inactivityTimeoutMs`. The token and API key in the connection URL are replaced with `[redacted]`, so the output is safe to log. To connect a CDP client, retrieve the session with an SDK or the API, and connect to its `websocketUrl`. See [CDP](https://steel.dev/docs/control/cdp).

### Exit codes

A command that fails prints the error, such as `stale_ref`, and exits with one of these codes. With `--json`, it prints `{"success": false, "error": ..., "error_code": ...}`.

| Code | Meaning |
| - | - |
| `0` | The command succeeded. |
| `1` | The command failed for a reason that the other codes do not cover. A `steel browser` command also exits with `1` for every Commands API error except `401` and `403`. |
| `3` | No sign-in or API key, or the API returned `401`. |
| `4` | The CLI could not reach the API. |
| `5` | The API returned another `4xx` status, such as `403`, `404` or `429`. |
| `6` | The API returned a `5xx` status. |

## `steel init`

Set up the CLI in one command: sign in, check the API connection, and install the agent skills.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--agent` | boolean | No | Run in agent mode, for AI coding agents: auto-accept interactive prompts and print agent-friendly output. |
| `--from` | string | No | The coding client to set up Steel for (opencode, claude-code, codex, pi). Works only with `--agent`. |
| `--skills` | string\[] | No | Skills to install. With no value, lets you choose them interactively. |
| `--no-skills` | boolean | No | Skip Steel skill installation. |

```sh
steel init
steel init --skills steel-browser,steel-developer
steel init --agent --from claude-code
```

## `steel login`

Sign in to Steel.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--resume` | boolean | No | Continue the saved authorization request; do not issue a new code. |
| `--no-wait` | boolean | No | Print the URL and code without waiting for approval. If a request is pending, check it once when a check is due. |
| `--no-browser` | boolean | No | Do not open a browser on this host. |

```sh
steel login
steel login --no-browser
steel login --resume
```

Aliases: `auth`.

## `steel logout`

End the sign-in and remove it from this computer.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--local-only` | boolean | No | Remove the sign-in from this computer without revoking it on the server, for when you are offline. |

```sh
steel logout
steel logout --local-only
```

## `steel scrape`

Scrape webpage content.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | Target URL to scrape. |
| `--format` | string | No | Comma-separated output formats: html, readability, cleaned_html, markdown. `markdown` by default. |
| `-d, --delay` | string | No | Delay before scraping in milliseconds. |
| `--pdf` | boolean | No | Include a generated PDF in the response. |
| `--screenshot` | boolean | No | Include a generated screenshot in the response. |
| `--use-proxy` | boolean | No | Use a Steel-managed residential proxy. |

```sh
steel scrape https://example.com
steel scrape https://example.com --format html,markdown --json
steel scrape https://example.com --delay 2000 --screenshot
```

## `steel screenshot`

Capture a screenshot of a webpage.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | Target URL to capture. |
| `-d, --delay` | string | No | Delay before capturing in milliseconds. |
| `-f, --full-page` | boolean | No | Capture a full-page screenshot. |
| `--use-proxy` | boolean | No | Use a Steel-managed residential proxy. |

```sh
steel screenshot https://example.com
steel screenshot https://example.com --full-page --delay 1000
```

## `steel pdf`

Generate a PDF from a webpage.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | Target URL to generate PDF from. |
| `-d, --delay` | string | No | Delay before generating in milliseconds. |
| `--use-proxy` | boolean | No | Use a Steel-managed residential proxy. |

```sh
steel pdf https://example.com
steel pdf https://example.com --delay 1000
```

## `steel browser`

Start, drive and stop browser sessions. [Names in the CLI and the MCP server](https://steel.dev/docs/reference/commands#names-in-the-cli-and-the-mcp-server) maps each subcommand to the command that it sends.

| Subcommand | Description |
| - | - |
| `start` | Create a browser session |
| `stop` | Stop a browser session |
| `sessions` | List the live sessions that this CLI started or attached to |
| `live` | Print the session viewer URL |
| `captcha` | Solve CAPTCHAs and check their status |
| `batch` | Run several browser commands in one request |
| `navigate` | Navigate to a URL |
| `back` | Navigate back in history |
| `forward` | Navigate forward in history |
| `reload` | Reload the current page |
| `click` | Click an element |
| `dblclick` | Double-click an element |
| `fill` | Fill an input field (replaces the current value). |
| `type` | Type text into an element key by key (appends to the current value). |
| `press` | Press a key or chord (Enter, Escape, Tab, Control+a). |
| `keydown` | Hold a key down until keyup |
| `keyup` | Release a key held with keydown |
| `hover` | Hover over an element |
| `focus` | Focus an element |
| `check` | Check a checkbox, radio button, or switch |
| `uncheck` | Uncheck a checkbox or switch |
| `select` | Select one or more options in a `select` element |
| `clear` | Clear an input field |
| `selectall` | Select all text in an input |
| `scroll` | Scroll the page or an element |
| `drag` | Drag an element onto another |
| `upload` | Upload files to a file input |
| `mouse` | Send mouse input to a point, for canvases and maps |
| `snapshot` | Take an accessibility tree snapshot with element refs |
| `screenshot` | Take a screenshot |
| `pdf` | Save the page as a PDF |
| `eval` | Run JavaScript in the page and print its value |
| `find` | Find elements and print their refs |
| `content` | Get the page HTML |
| `get` | Get information about elements or the page |
| `is` | Check element state |
| `wait` | Wait for an element, text, URL, load state, download, or a fixed time |
| `tab` | List, open, switch, or close tabs |
| `status` | Wait for a command that is still running |
| `cancel` | Stop a command that is still running |

### `steel browser start`

Create a browser session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--stealth` | boolean | No | Turns on `humanizeInteractions` and CAPTCHA solving (`solveCaptcha`). On Launch, CAPTCHA solving needs a verified account. |
| `-p, --proxy` | string | No | Your own proxy server, as `http://username:password@hostname:port`. Sent as `proxyUrl`. |
| `--timeout` | string | No | Session timeout in milliseconds. 900000 (15 minutes) by default, which every plan allows. |
| `--inactivity-timeout` | string | No | Inactivity timeout in milliseconds. Steel releases the session when no command, CDP message or input from the live view arrives for this long. 600000 (10 minutes) by default. Pass 0 to turn it off. It has no effect when it is equal to or longer than `--timeout`. |
| `--solve-captcha` | boolean | No | Turns on CAPTCHA solving (`solveCaptcha`). Steel solves each CAPTCHA that it detects. On Launch, CAPTCHA solving needs a verified account. |
| `--profile` | string | No | Named profile to load (see `steel profile list`). |
| `--update-profile` | boolean | No | Save session state back to the profile when the session ends; creates the profile if it does not exist. Needs `--profile`. Do not use it with `--credentials`, as [Use credentials with a profile](https://steel.dev/docs/logins/credentials#use-credentials-with-a-profile) explains. |
| `--namespace` | string | No | Credential namespace. |
| `--credentials` | boolean | No | Fill stored credentials into sign-in forms. |
| `--metadata` | string\[] | No | Attach metadata as KEY=VALUE, repeatable (Steel Cloud only). |

```sh
steel browser start --timeout 900000
steel browser start --session checkout --metadata env=staging
steel browser start --session app --profile my-app --update-profile
```

### `steel browser stop`

Stop a browser session.

Aliases: `close`, `quit`, `exit`.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-a, --all` | boolean | No | Stop every session this CLI started. Sessions you only attached to by ID are forgotten, not stopped. |

```sh
steel browser stop
steel browser stop --session checkout
steel browser stop --all
```

### `steel browser sessions`

List the live sessions that this CLI started or attached to.

### `steel browser live`

Print the session viewer URL, where you watch the session live. The command does not open a browser.

### `steel browser captcha`

Solve CAPTCHAs and check their status.

| Subcommand | Description |
| - | - |
| `solve` | Solve the CAPTCHAs that Steel detected in the session |
| `status` | Check CAPTCHA status, and list the IDs of each page and task |

#### `steel browser captcha solve`

Solve the CAPTCHAs that Steel detected in the session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--page-id` | string | No | Solve only the CAPTCHAs on the page with this ID. |
| `--url` | string | No | Solve only the CAPTCHAs on the page with this URL. |
| `--task-id` | string | No | Solve only the CAPTCHA with this task ID. |

```sh
steel browser captcha solve
steel browser captcha solve --url https://example.com/login
```

#### `steel browser captcha status`

Check CAPTCHA status. The CLI prints the overall status, then one line for each page and each task, with its ID. Pass these IDs to `captcha solve` with `--page-id` or `--task-id`. With `--json`, the IDs are under `data.pages`.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--page-id` | string | No | Check only the page with this ID. |
| `-w, --wait` | boolean | No | Wait until the status is `solved`, `failed` or `none`. |
| `--timeout` | string | No | Timeout in milliseconds for --wait mode. 60000 by default. |
| `--interval` | string | No | Poll interval in milliseconds for --wait mode. 1000 by default. |

```sh
steel browser captcha status
steel browser captcha status --wait --timeout 120000
```

### `steel browser batch`

Run several browser commands in one request.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `commands` | string\[] | Yes | Commands to run in order, each as one string (for example "click e3" or "fill e3 'New York'"). They stop at the first failure. |

```sh
steel browser batch "fill e3 'Ada Lovelace'" "check e5" "click e7"
steel browser batch "open https://example.com" "snapshot -i"
```

### `steel browser navigate`

Navigate to a URL.

Aliases: `open`, `goto`.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | URL to navigate to. |
| `--wait-until` | enum | No | Wait condition: load, domcontentloaded, networkidle. |

```sh
steel browser navigate https://example.com
steel browser open https://example.com --wait-until networkidle
```

### `steel browser back`

Navigate back in history.

### `steel browser forward`

Navigate forward in history.

### `steel browser reload`

Reload the current page.

### `steel browser click`

Click an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |
| `--count` | string | No | Number of clicks (2 for double-click). |

```sh
steel browser click e5
steel browser click "button[type=submit]"
steel browser click e5 --count 2
```

### `steel browser dblclick`

Double-click an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser dblclick e5
```

### `steel browser fill`

Fill an input field (replaces the current value).

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref or CSS selector. |
| `value` | string\[] | No | Value to fill. |

```sh
steel browser fill e3 "ada@example.com"
steel browser fill "input[name=email]" "ada@example.com"
```

### `steel browser type`

Type text into an element key by key (appends to the current value).

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref or CSS selector. |
| `text` | string\[] | No | Text to type. |
| `--clear` | boolean | No | Clear the field before typing. |
| `--delay` | string | No | Delay between keystrokes in milliseconds (at most 1000). |

```sh
steel browser type e3 "steel browser"
steel browser type e3 "new text" --clear --delay 50
```

### `steel browser press`

Press a key or chord (Enter, Escape, Tab, Control+a).

Aliases: `key`.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `key` | string | Yes | Key to press (for example Enter, Escape, Tab, Control+a). |

```sh
steel browser press Enter
steel browser press Control+a
```

When a JavaScript dialog is open on the current tab, `steel browser press Enter` accepts it, and `steel browser press Escape` dismisses it. The CLI sends the key to the current tab, so when the dialog is on another tab, run `steel browser tab switch` with that tab's ID first. A person can also answer the dialog in the [live view](https://steel.dev/docs/observability/live-view). See [Dialogs](https://steel.dev/docs/reference/commands#dialogs).

### `steel browser keydown`

Hold a key down until keyup.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `key` | string | Yes | Key name (for example Shift, Control, ArrowDown). |

```sh
steel browser keydown Shift
steel browser press ArrowDown
steel browser keyup Shift
```

### `steel browser keyup`

Release a key held with keydown.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `key` | string | Yes | Key name (for example Shift, Control, ArrowDown). |

```sh
steel browser keyup Shift
```

### `steel browser hover`

Hover over an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser hover e4
```

### `steel browser focus`

Focus an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser focus e3
```

### `steel browser check`

Check a checkbox, radio button, or switch.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser check e5
steel browser check "#terms"
```

### `steel browser uncheck`

Uncheck a checkbox or switch.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser uncheck e5
```

### `steel browser select`

Select one or more options in a `select` element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Ref or CSS selector of the `select` element. |
| `values` | string\[] | No | The values or labels of the options to select. |

```sh
steel browser select e4 "South Korea"
steel browser select e6 cheese olives
```

### `steel browser clear`

Clear an input field.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser clear e3
```

### `steel browser selectall`

Select all text in an input.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser selectall e3
```

### `steel browser scroll`

Scroll the page or an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `direction` | enum | No | Direction: up, down, left, right (default: down). |
| `amount` | string | No | Scroll amount in pixels (default: 300). |
| `-s, --selector` | string | No | Element to scroll instead of the page. |

```sh
steel browser scroll down 600
steel browser scroll up
steel browser scroll down 300 --selector "#results"
```

### `steel browser drag`

Drag an element onto another.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `source` | string | Yes | Element to drag (ref or CSS selector). |
| `target` | string | Yes | Element to drop on (ref or CSS selector). |

```sh
steel browser drag e8 e9
```

### `steel browser upload`

Upload files to a file input.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | File input ref or CSS selector. |
| `files` | string\[] | No | Local files to upload, or names of files already in the session. |

```sh
steel browser upload e6 ./resume.pdf
```

### `steel browser mouse`

Send mouse input to a point, for canvases and maps.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `action` | enum | Yes | move, down, up, click, or wheel. |
| `x` | string | No | X in CSS pixels of the visible page (needed for move, click, and wheel). |
| `y` | string | No | Y in CSS pixels of the visible page (needed for move, click, and wheel). |
| `--button` | enum | No | Mouse button: left, right, middle. |
| `--clicks` | string | No | Click count for click (1 to 3). |
| `--dx` | string | No | Horizontal wheel delta. |
| `--dy` | string | No | Vertical wheel delta. |

```sh
steel browser mouse click 250 380
steel browser mouse click 250 380 --button right
steel browser mouse wheel 250 380 --dy 500
```

### `steel browser snapshot`

Take an accessibility tree snapshot with element refs.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-i, --interactive` | boolean | No | Show only the elements that have a ref. |
| `-c, --compact` | boolean | No | Keep only lines with refs or values, and their ancestors. |
| `-d, --max-depth` | string | No | Maximum nesting depth. |

```sh
steel browser snapshot -i
steel browser snapshot -c -d 5
```

### `steel browser screenshot`

Take a screenshot.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-f, --full-page` | boolean | No | Capture the full scrollable page. |
| `-o, --output` | string | No | Output file path. `screenshot.png` by default. |
| `--selector` | string | No | Capture one element (ref or CSS selector). |
| `--format` | enum | No | Image format: png, jpeg, webp (default: from the output extension). |
| `--quality` | string | No | JPEG/WebP quality (0-100). |

```sh
steel browser screenshot
steel browser screenshot -o page.png --full-page
steel browser screenshot --selector e2 -o heading.png
```

### `steel browser pdf`

Save the page as a PDF. It works in headful and headless sessions.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-o, --output` | string | No | Output file path. `page.pdf` by default. |
| `--landscape` | boolean | No | Use landscape orientation. |
| `--print-background` | boolean | No | Print background graphics. |

```sh
steel browser pdf
steel browser pdf -o invoice.pdf --landscape --print-background
```

### `steel browser eval`

Run JavaScript in the page and print its value.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `script` | string | Yes | JavaScript to run on the page. The CLI prints the value of its last expression. A `return` outside a function fails. |
| `--timeout` | string | No | Time limit in milliseconds. 10000 by default, and at most 50000. |

```sh
steel browser eval "document.title"
steel browser eval "[...document.querySelectorAll('a')].map(a => a.href)"
```

### `steel browser find`

Find elements and print their refs.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `value` | string | Yes | What to look for (a CSS selector unless --by says otherwise). |
| `--by` | enum | No | Locator kind: css, role, text, label, placeholder, alt, title, testid. `css` by default. |
| `--name` | string | No | Accessible name, with --by role. |
| `--exact` | boolean | No | Match the text exactly instead of as a case-insensitive substring. |

```sh
steel browser find "a[href]"
steel browser find button --by role --name "Create account"
steel browser find Email --by label
```

### `steel browser content`

Get the page HTML.

```sh
steel browser content > page.html
```

### `steel browser get`

Get information about elements or the page.

| Subcommand | Description |
| - | - |
| `text` | Get the visible text of an element |
| `html` | Get the inner HTML of an element |
| `markdown` | Get the main content of an element or the page as Markdown |
| `value` | Get an input or textarea value |
| `attr` | Get an element attribute |
| `url` | Get the page URL |
| `title` | Get the page title |
| `count` | Count matching elements |
| `box` | Get an element's bounding box |

#### `steel browser get text`

Get the visible text of an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser get text e2
```

#### `steel browser get html`

Get the inner HTML of an element.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser get html "#status"
```

#### `steel browser get markdown`

Get the main content of an element or the page as Markdown.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | No | Element ref (for example e5) or CSS selector; the whole page if omitted. |

```sh
steel browser get markdown
steel browser get markdown article
```

#### `steel browser get value`

Get an input or textarea value.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser get value e3
```

#### `steel browser get attr`

Get an element attribute.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref or CSS selector. |
| `attribute` | string | Yes | Attribute name. |

```sh
steel browser get attr e1 href
```

#### `steel browser get url`

Get the page URL.

#### `steel browser get title`

Get the page title.

#### `steel browser get count`

Count matching elements.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | CSS selector, not a ref. |

```sh
steel browser get count "input[type=checkbox]"
```

#### `steel browser get box`

Get an element's bounding box.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser get box e5
```

### `steel browser is`

Check element state.

| Subcommand | Description |
| - | - |
| `visible` | Check if an element is visible |
| `enabled` | Check if an element is enabled |
| `checked` | Check if an element is checked |

#### `steel browser is visible`

Check if an element is visible.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser is visible e5
```

#### `steel browser is enabled`

Check if an element is enabled.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser is enabled e7
```

#### `steel browser is checked`

Check if an element is checked.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `selector` | string | Yes | Element ref (for example e5) or CSS selector. |

```sh
steel browser is checked e5
```

### `steel browser wait`

Wait for an element, text, URL, load state, download, or a fixed time.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `ms` | string | No | Fixed time to wait in milliseconds (at most 30000). |
| `--timeout` | string | No | Timeout in milliseconds (at most 50000). 30000 by default. |
| `-t, --text` | string | No | Wait for text to appear on the page. |
| `--selector` | string | No | Wait for an element (ref or CSS selector). |
| `--state` | enum | No | Element state: visible, hidden, attached, detached. |
| `-u, --url` | string | No | Wait until the URL contains this text, or matches a pattern with `*`. See [`wait`](https://steel.dev/docs/reference/commands#wait) in the Commands reference. |
| `-l, --load-state` | enum | No | Wait for a load state: load, domcontentloaded, networkidle. |
| `--download` | boolean | No | Wait for a download to finish and save it. |
| `-o, --output` | string | No | Where to save the download (default: its file name in the current directory). |

```sh
steel browser wait --text "Saved"
steel browser wait --selector e5 --state hidden
steel browser wait --download -o report.pdf
```

### `steel browser tab`

List, open, switch, or close tabs.

| Subcommand | Description |
| - | - |
| `list` | List open tabs |
| `new` | Open a new tab and switch to it |
| `switch` | Switch to a tab |
| `close` | Close a tab (the current tab if omitted). |

#### `steel browser tab list`

List open tabs.

#### `steel browser tab new`

Open a new tab and switch to it.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `url` | string | No | URL to open (defaults to about:blank). |

```sh
steel browser tab new https://example.com
```

#### `steel browser tab switch`

Switch to a tab.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `tab` | string | Yes | Tab ID from `tab list`, such as t2. |

```sh
steel browser tab switch t2
```

#### `steel browser tab close`

Close a tab (the current tab if omitted).

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `tab` | string | No | Tab ID from `tab list`, such as t2. |

```sh
steel browser tab close t2
```

### `steel browser status`

Wait for a command that is still running.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `execution` | string | Yes | Execution ID such as x-7. |

```sh
steel browser status x-7
```

### `steel browser cancel`

Stop a command that is still running. Ctrl-C while a command runs also cancels it. Press Ctrl-C again to stop waiting for the cancel.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `execution` | string | Yes | Execution ID such as x-7. |

```sh
steel browser cancel x-7
```

## `steel sessions`

List, inspect and release cloud sessions, and read their logs and traces.

| Subcommand | Description |
| - | - |
| `list` | List cloud sessions |
| `get` | Get one cloud session |
| `metadata` | Show or change a session's metadata |
| `release` | Release a cloud session |
| `logs` | Read browser event logs for a session |
| `agent-logs` | Read raw CDP-derived agent events for a session |
| `traces` | Read the agent trace timeline for a session |

### `steel sessions list`

List cloud sessions.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--limit` | string | No | Number of sessions to return. |
| `--cursor-id` | string | No | Cursor ID for pagination. |
| `--status` | string | No | Filter by status: live, released, or failed. |
| `--metadata` | string\[] | No | Filter by metadata KEY=VALUE, repeatable; all must match. |
| `--signal` | string\[] | No | Filter by signal, repeatable or comma-separated; all must match. Signals arrive after the session ends: captcha_encountered, proxy_connection_failed, session_timeout_exceeded, bot_detection_triggered, context_restored. |
| `--release-reason` | string | No | Filter by release reason: user_requested, timeout, inactivity_timeout, creation_timeout, startup_failed, browser_closed, or browser_crashed. |
| `--created-after` | string | No | Only sessions created at or after this ISO 8601 timestamp. |
| `--created-before` | string | No | Only sessions created before this ISO 8601 timestamp. |

```sh
steel sessions list --status live --limit 20
steel sessions list --metadata env=staging
steel sessions list --signal captcha_encountered --created-after 2026-11-01T00:00:00Z
```

API: `GET /v1/sessions`.

### `steel sessions get`

Get one cloud session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | No | Cloud session ID. |
| `--session` | string | No | The name of a `steel browser` session, instead of the session ID. |

```sh
steel sessions get SESSION_ID
steel sessions get --session checkout
```

API: `GET /v1/sessions/{id}`.

### `steel sessions metadata`

Show or change a session's metadata.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | No | Cloud session ID. |
| `--session` | string | No | The name of a `steel browser` session, instead of the session ID. |
| `--set` | string\[] | No | Set a key as KEY=VALUE, repeatable; other keys are kept. |
| `--unset` | string\[] | No | Remove a key, repeatable. |
| `--replace` | boolean | No | Replace all metadata with exactly the --set keys. |
| `--clear` | boolean | No | Remove all metadata. |

```sh
steel sessions metadata SESSION_ID
steel sessions metadata SESSION_ID --set outcome=failed --unset retry
steel sessions metadata SESSION_ID --replace --set env=prod
```

Without a flag that changes something, the command prints the metadata, one `KEY=VALUE` on each line.

API: `GET /v1/sessions/{id}`, `PATCH /v1/sessions/{id}/metadata`, `PUT /v1/sessions/{id}/metadata`.

### `steel sessions release`

Release a cloud session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | No | Cloud session ID. |
| `-a, --all` | boolean | No | Release all live cloud sessions. |
| `--session` | string | No | The name of a `steel browser` session, instead of the session ID. |

```sh
steel sessions release SESSION_ID
steel sessions release --all
```

API: `POST /v1/sessions/{id}/release`, `POST /v1/sessions/release`.

### `steel sessions logs`

Read browser event logs for a session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | No | Cloud session ID. |
| `--session` | string | No | The name of a `steel browser` session, instead of the session ID. |
| `-f, --follow` | boolean | No | After printing past events, stream live ones over a WebSocket. |
| `--namespace` | string | No | Filter by namespace. |
| `--start-time` | string | No | ISO timestamp lower bound. |
| `--since` | string | No | Alias for --start-time. |
| `--end-time` | string | No | ISO timestamp upper bound. |
| `--event-type` | string\[] | No | Event type filter, repeatable or comma-separated. |
| `--limit` | string | No | Number of events to return. |
| `--offset` | string | No | Pagination offset. |

```sh
steel sessions logs SESSION_ID --follow
steel sessions logs SESSION_ID --event-type PageError,RequestFailed --limit 50
```

API: `GET /v1/sessions/{id}/logs`.

### `steel sessions agent-logs`

Read raw CDP-derived agent events for a session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | No | Cloud session ID. |
| `--session` | string | No | The name of a `steel browser` session, instead of the session ID. |
| `--namespace` | string | No | Filter by namespace. |
| `--start-time` | string | No | ISO timestamp lower bound. |
| `--since` | string | No | Alias for --start-time. |
| `--end-time` | string | No | ISO timestamp upper bound. |
| `--event-type` | string\[] | No | Event type filter, repeatable or comma-separated. |
| `--limit` | string | No | Number of events to return. |
| `--offset` | string | No | Pagination offset. |

```sh
steel sessions agent-logs SESSION_ID --limit 100
```

API: `GET /v1/sessions/{id}/agent-logs`.

### `steel sessions traces`

Read the agent trace timeline for a session.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | No | Cloud session ID. |
| `--session` | string | No | The name of a `steel browser` session, instead of the session ID. |
| `-f, --follow` | boolean | No | After printing past traces, stream live ones over a WebSocket. |
| `--namespace` | string | No | Filter by namespace. |
| `--start-time` | string | No | ISO timestamp lower bound. |
| `--since` | string | No | Alias for --start-time. |
| `--end-time` | string | No | ISO timestamp upper bound. |
| `--event-type` | string\[] | No | Event type filter, repeatable or comma-separated. |

```sh
steel sessions traces SESSION_ID
steel sessions traces SESSION_ID --follow
```

API: `GET /v1/sessions/{id}/agent-traces`.

## `steel credentials`

Manage stored credentials.

| Subcommand | Description |
| - | - |
| `list` | List stored credentials |
| `create` | Create a new credential |
| `update` | Update an existing credential |
| `delete` | Delete a credential |

### `steel credentials list`

List stored credentials.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-n, --namespace` | string | No | The namespace to list, `default` when you leave this out. The command lists one namespace at a time. |
| `--origin` | string | No | Filter by origin URL. |

```sh
steel credentials list
steel credentials list --namespace team-a --origin https://example.com
```

### `steel credentials create`

Create a new credential.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--origin` | string | Yes | Origin URL to associate the credential with. |
| `-u, --username` | string | Yes | Username. |
| `-p, --password` | string | Yes | Password. |
| `--totp-secret` | string | No | TOTP secret for two-factor authentication. |
| `-n, --namespace` | string | No | Credential namespace. |
| `--label` | string | No | Human-readable label. |

```sh
steel credentials create \
  --origin https://example.com \
  --username ada@example.com \
  --password "$PASSWORD" \
  --totp-secret "$TOTP_SECRET" \
  --namespace team-a
```

### `steel credentials update`

Update an existing credential.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--origin` | string | Yes | Origin URL of the credential to update. |
| `-u, --username` | string | No | New username. |
| `-p, --password` | string | No | New password. |
| `--totp-secret` | string | No | New TOTP secret. |
| `-n, --namespace` | string | No | Credential namespace. |
| `--label` | string | No | New human-readable label. |

```sh
steel credentials update --origin https://example.com --password "$PASSWORD"
steel credentials update --origin https://example.com --namespace team-a --label "Example admin"
```

### `steel credentials delete`

Delete a credential.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--origin` | string | Yes | Origin URL of the credential to delete. |
| `-n, --namespace` | string | No | Credential namespace. |

```sh
steel credentials delete --origin https://example.com --namespace team-a
```

## `steel dev`

Install, start and stop the local Steel Browser runtime.

| Subcommand | Description |
| - | - |
| `install` | Install the local Steel Browser runtime |
| `start` | Start the local runtime containers |
| `stop` | Stop the local runtime containers |

### `steel dev install`

Install the local Steel Browser runtime.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--repo-url` | string | No | Git repository URL for local Steel Browser runtime. |
| `-V, --verbose` | boolean | No | Enable verbose git command output. |

```sh
steel dev install
steel dev install --repo-url https://github.com/OWNER/steel-browser.git
```

### `steel dev start`

Start the local runtime containers.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-p, --port` | string | No | API port for local Steel Browser runtime. |
| `-V, --verbose` | boolean | No | Enable verbose Docker command output. |
| `-d, --docker-check` | boolean | No | Only verify Docker availability and exit. |

```sh
steel dev start
steel dev start --docker-check
```

### `steel dev stop`

Stop the local runtime containers.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-V, --verbose` | boolean | No | Enable verbose Docker command output. |

## `steel forge`

Scaffold a new project from a template.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `template` | string | No | Template to start from. |
| `-n, --name` | string | No | Project name. |
| `--list` | boolean | No | List available templates and exit (respects --json). |

```sh
steel forge --list
steel forge playwright-ts --name my-agent
```

## `steel config`

Show current configuration.

## `steel update`

Update to the latest version.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-f, --force` | boolean | No | Force update even if already on latest version. |
| `-c, --check` | boolean | No | Only check for updates without installing. |

```sh
steel update --check
steel update
```

## `steel cache`

Manage Steel CLI cache.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `-c, --clean` | boolean | No | Remove all cached files and directories. |

```sh
steel cache
steel cache --clean
```

## `steel profile`

Manage named Steel browser profiles.

| Subcommand | Description |
| - | - |
| `list` | List the profile names saved on this computer |
| `import` | Import a local browser profile into Steel |
| `sync` | Sync a local browser profile to an existing Steel profile |
| `delete` | Forget a profile name on this computer |

### `steel profile list`

List the profile names that the CLI saved on this computer, with their profile IDs.

### `steel profile import`

Import a local browser profile into Steel.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Steel profile name to save as. |
| `--from` | string | No | Browser profile directory to import from (for example "Default", "Profile 1"). |
| `--browser` | string | No | Browser to import from (chrome, edge, brave, arc, opera, vivaldi). |
| `--full` | boolean | No | Include all profile data such as IndexedDB, History and Bookmarks. |

```sh
steel profile import my-app
steel profile import my-app --browser chrome --from "Profile 1"
```

### `steel profile sync`

Sync a local browser profile to an existing Steel profile.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Steel profile name to sync. |
| `--from` | string | No | Browser profile directory to sync from (overrides stored source). |
| `--browser` | string | No | Browser to sync from (overrides stored browser). |
| `--full` | boolean | No | Include all profile data such as IndexedDB, History and Bookmarks. |

```sh
steel profile sync my-app
steel profile sync my-app --full
```

### `steel profile delete`

Forget a profile name on this computer. The profile and its browser state stay in Steel.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Profile name to forget. |

```sh
steel profile delete my-app
```

## `steel describe`

Describe commands and parameters.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `path` | string\[] | No | Command path to describe (for example "browser click"). |
| `--all` | boolean | No | Print the whole command tree. |

```sh
steel describe browser click
steel describe --all
```

## `steel doctor`

Check environment, auth, and connectivity.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--preflight` | boolean | No | Only check auth and API connectivity. |

```sh
steel doctor
steel doctor --preflight
```

## `steel skills`

Manage Steel agent skills.

| Subcommand | Description |
| - | - |
| `list` | List available Steel skills |
| `install` | Install all or selected Steel skills through npx skills |
| `update` | Update one or more installed Steel skills through npx skills |
| `doctor` | Check Steel skills installation health |
| `open` | Open an installed skill, or its docs page when it is not installed |
| `paths` | Show detected agent install paths for Steel skills |

### `steel skills list`

List available Steel skills.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--offline` | boolean | No | Use the cached or bundled manifest instead of fetching it from GitHub. |

```sh
steel skills list
steel skills list --offline
```

### `steel skills install`

Install all or selected Steel skills through npx skills.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `names` | string\[] | Yes, unless `--all` | The names of the skills to install. |
| `--all` | boolean | No | Install all Steel skills from the catalog. |
| `-a, --agent` | string | No | Target agent passed to npx skills (-a). |
| `-g, --global` | boolean | No | Install globally through npx skills (-g). |
| `-y, --yes` | boolean | No | Answer yes to every prompt of npx skills (-y). |

```sh
steel skills install steel-browser
steel skills install steel-browser steel-developer -a claude-code -g
steel skills install --all --yes
```

### `steel skills update`

Update one or more installed Steel skills through npx skills.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `names` | string\[] | No | The names of the skills to update. Without names, every Steel skill updates. |
| `-y, --yes` | boolean | No | Answer yes to every prompt of npx skills (-y). |

```sh
steel skills update
steel skills update steel-browser --yes
```

### `steel skills doctor`

Check Steel skills installation health.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `--offline` | boolean | No | Use the cached or bundled manifest instead of fetching it from GitHub. |

```sh
steel skills doctor
steel skills doctor --offline
```

### `steel skills open`

Open an installed skill, or its docs page when it is not installed.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Skill name. |

```sh
steel skills open steel-browser
```

### `steel skills paths`

Show detected agent install paths for Steel skills.

## `steel completion`

Generate a shell completion script.

| Argument or flag | Type | Required | Description |
| - | - | - | - |
| `shell` | enum | Yes | Shell to generate completions for: bash, zsh, fish, powershell, elvish. |

```sh
steel completion zsh > ~/.zsh/completions/_steel
steel completion bash > ~/.local/share/bash-completion/completions/steel
steel completion fish > ~/.config/fish/completions/steel.fish
```

The install script writes the completion for your shell to the same path.
