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 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. ~/. 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.
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. |
steel init
steel init --skills steel-browser,steel-developer
steel init --agent --from claude-codesteel 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. |
steel login
steel login --no-browser
steel login --resumeAliases: 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. |
steel logout
steel logout --local-onlysteel 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. |
steel scrape https://example.com
steel scrape https://example.com --format html,markdown --json
steel scrape https://example.com --delay 2000 --screenshotsteel 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. |
steel screenshot https://example.com
steel screenshot https://example.com --full-page --delay 1000steel 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. |
steel pdf https://example.com
steel pdf https://example.com --delay 1000steel browser
Start, drive and stop browser sessions. 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://. 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 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). |
steel browser start --timeout 900000
steel browser start --session checkout --metadata env=staging
steel browser start --session app --profile my-app --update-profilesteel 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. |
steel browser stop
steel browser stop --session checkout
steel browser stop --allsteel 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. |
steel browser captcha solve
steel browser captcha solve --url https://example.com/loginsteel 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. |
steel browser captcha status
steel browser captcha status --wait --timeout 120000steel 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. |
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. |
steel browser navigate https://example.com
steel browser open https://example.com --wait-until networkidlesteel 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). |
steel browser click e5
steel browser click "button[type=submit]"
steel browser click e5 --count 2steel browser dblclick
Double-click an element.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
selector | string | Yes | Element ref (for example e5) or CSS selector. |
steel browser dblclick e5steel 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. |
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). |
steel browser type e3 "steel browser"
steel browser type e3 "new text" --clear --delay 50steel 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). |
steel browser press Enter
steel browser press Control+aWhen 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. See 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). |
steel browser keydown Shift
steel browser press ArrowDown
steel browser keyup Shiftsteel browser keyup
Release a key held with keydown.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Key name (for example Shift, Control, ArrowDown). |
steel browser keyup Shiftsteel browser hover
Hover over an element.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
selector | string | Yes | Element ref (for example e5) or CSS selector. |
steel browser hover e4steel browser focus
Focus an element.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
selector | string | Yes | Element ref (for example e5) or CSS selector. |
steel browser focus e3steel 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. |
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. |
steel browser uncheck e5steel 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. |
steel browser select e4 "South Korea"
steel browser select e6 cheese olivessteel browser clear
Clear an input field.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
selector | string | Yes | Element ref (for example e5) or CSS selector. |
steel browser clear e3steel 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. |
steel browser selectall e3steel 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. |
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). |
steel browser drag e8 e9steel 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. |
steel browser upload e6 ./resume.pdfsteel 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. |
steel browser mouse click 250 380
steel browser mouse click 250 380 --button right
steel browser mouse wheel 250 380 --dy 500steel 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. |
steel browser snapshot -i
steel browser snapshot -c -d 5steel 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. 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). |
steel browser screenshot
steel browser screenshot -o page.png --full-page
steel browser screenshot --selector e2 -o heading.pngsteel 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. by default. |
--landscape | boolean | No | Use landscape orientation. |
--print-background | boolean | No | Print background graphics. |
steel browser pdf
steel browser pdf -o invoice.pdf --landscape --print-backgroundsteel 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. |
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. |
steel browser find "a[href]"
steel browser find button --by role --name "Create account"
steel browser find Email --by labelsteel browser content
Get the page HTML.
steel browser content > page.htmlsteel 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. |
steel browser get text e2steel 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. |
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. |
steel browser get markdown
steel browser get markdown articlesteel 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. |
steel browser get value e3steel 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. |
steel browser get attr e1 hrefsteel 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. |
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. |
steel browser get box e5steel 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. |
steel browser is visible e5steel 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. |
steel browser is enabled e7steel 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. |
steel browser is checked e5steel 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 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). |
steel browser wait --text "Saved"
steel browser wait --selector e5 --state hidden
steel browser wait --download -o report.pdfsteel 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). |
steel browser tab new https://example.comsteel browser tab switch
Switch to a tab.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
tab | string | Yes | Tab ID from tab list, such as t2. |
steel browser tab switch t2steel 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. |
steel browser tab close t2steel 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. |
steel browser status x-7steel 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. |
steel browser cancel x-7steel 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. |
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:00ZAPI: 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. |
steel sessions get SESSION_ID
steel sessions get --session checkoutAPI: 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. |
steel sessions metadata SESSION_ID
steel sessions metadata SESSION_ID --set outcome=failed --unset retry
steel sessions metadata SESSION_ID --replace --set env=prodWithout 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. |
steel sessions release SESSION_ID
steel sessions release --allAPI: 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. |
steel sessions logs SESSION_ID --follow
steel sessions logs SESSION_ID --event-type PageError,RequestFailed --limit 50API: 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. |
steel sessions agent-logs SESSION_ID --limit 100API: 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. |
steel sessions traces SESSION_ID
steel sessions traces SESSION_ID --followAPI: 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. |
steel credentials list
steel credentials list --namespace team-a --origin https://example.comsteel 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. |
steel credentials create \
--origin https://example.com \
--username ada@example.com \
--password "$PASSWORD" \
--totp-secret "$TOTP_SECRET" \
--namespace team-asteel 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. |
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. |
steel credentials delete --origin https://example.com --namespace team-asteel 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. |
steel dev install
steel dev install --repo-url https://github.com/OWNER/steel-browser.gitsteel 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. |
steel dev start
steel dev start --docker-checksteel 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). |
steel forge --list
steel forge playwright-ts --name my-agentsteel 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. |
steel update --check
steel updatesteel cache
Manage Steel CLI cache.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
-c, --clean | boolean | No | Remove all cached files and directories. |
steel cache
steel cache --cleansteel 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. |
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. |
steel profile sync my-app
steel profile sync my-app --fullsteel 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. |
steel profile delete my-appsteel 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. |
steel describe browser click
steel describe --allsteel doctor
Check environment, auth, and connectivity.
| Argument or flag | Type | Required | Description |
|---|---|---|---|
--preflight | boolean | No | Only check auth and API connectivity. |
steel doctor
steel doctor --preflightsteel 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. |
steel skills list
steel skills list --offlinesteel 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). |
steel skills install steel-browser
steel skills install steel-browser steel-developer -a claude-code -g
steel skills install --all --yessteel 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). |
steel skills update
steel skills update steel-browser --yessteel 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. |
steel skills doctor
steel skills doctor --offlinesteel 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. |
steel skills open steel-browsersteel 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. |
steel completion zsh > ~/.zsh/completions/_steel
steel completion bash > ~/.local/share/bash-completion/completions/steel
steel completion fish > ~/.config/fish/completions/steel.fishThe install script writes the completion for your shell to the same path.