---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/control/cli
markdown_url: https://steel.dev/docs/control/cli.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: CLI
description: Install the Steel CLI, sign in, and drive a cloud browser from your terminal with steel browser, or get a page with steel scrape.
summary: Install the Steel CLI, sign in, and drive a cloud browser from your terminal with steel browser, or get a page with steel scrape.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/control.md
  - https://steel.dev/docs/control/snapshots-and-refs.md
related:
  - https://steel.dev/docs/control.md
  - https://steel.dev/docs/control/snapshots-and-refs.md
  - https://steel.dev/docs/control/skills.md
  - https://steel.dev/docs/control/mcp-server.md
  - https://steel.dev/docs/control/cdp.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# CLI

The Steel CLI is the `steel` command. It drives cloud browsers from your terminal: open a page, read it as a snapshot, click and type, and stop the session. It also runs the Quick actions, such as `steel scrape`, which returns a page as Markdown. Use it to try Steel without writing code, in shell scripts, and in coding agents, which run `steel` commands as tools. [CLI commands](https://steel.dev/docs/reference/cli) lists every command and flag.

## Install the CLI

Run the install script:

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

The script installs the `steel` binary in `~/.steel/bin`, adds that folder to `PATH` in your shell's startup file, and sets up shell completions for bash, zsh and fish. In an interactive terminal, it then runs `steel init`, which signs you in, checks the connection and offers to install the [skills](https://steel.dev/docs/control/skills) for coding agents. To install only, pass `--non-interactive` to the script:

```sh
curl -fsS https://setup.steel.dev | sh -s -- --non-interactive
```

The script does not update the current shell's `PATH`. Open a new terminal, or run:

```sh
export PATH="$HOME/.steel/bin:$PATH"
```

You can also download the binary from [GitHub Releases](https://github.com/steel-dev/cli/releases).

## Sign in

Run `steel login`. It prints a URL and a short code, and it opens the URL in your browser. Check that the browser shows the same code, and approve it. The CLI then keeps the sign-in in `~/.config/steel/auth.json`.

```sh
steel login
```

You can approve the code in a browser on any machine. On a machine without a browser, run `steel login --no-browser`, and open the URL on another device. If the command stops before you approve, run `steel login --resume` to continue with the same code.

For a machine where no person signs in, such as a CI runner, set the `STEEL_API_KEY` environment variable instead. When you have both a sign-in and `STEEL_API_KEY`, the CLI uses `STEEL_API_KEY`.

To check the sign-in and connection to Steel, run:

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

`steel logout` ends the sign-in and removes it from the machine.

## Drive a browser

`steel browser` drives a cloud browser. Each command is one request to the session's [Commands](https://steel.dev/docs/control/commands) API, so the CLI keeps no process running between commands.

```sh
steel browser open https://example.com
steel browser snapshot -i
steel browser click e1
steel browser stop
```

The first command starts a session named `default`. `snapshot -i` prints only the elements that have a [ref](https://steel.dev/docs/control/snapshots-and-refs):

```text nocopy
- link "Learn more" [ref=e1]
```

To watch the session, print its live view URL, and open it in a browser where you are signed in to Steel. After `steel browser stop`, the same URL replays the session:

```sh
steel browser live
```

```text nocopy
https://app.steel.dev/sessions/de8b6f7b-eb68-4599-ba40-ee5fb3cefa69
```

Pass a ref, such as `e1`, or a CSS selector to the commands that act on an element:

```sh
steel browser click e1
steel browser wait --load-state networkidle
steel browser get title
```

Add `--diff` to any command to print what it changed on the page, compared with your last snapshot. To run several commands in one request, use `batch`. The commands run in order and stop at the first failure:

```sh
steel browser batch "click e1" "snapshot -i"
```

A ref fails with `stale_ref` when its element left the page. In that case, take a new snapshot. A command that fails prints the error code and exits with code 1. [Exit codes](https://steel.dev/docs/reference/cli#exit-codes) lists the other codes.

When a page opens a JavaScript dialog, commands on its tab fail until the dialog closes. Run `steel browser press Enter` to accept the dialog, or `steel browser press Escape` to dismiss it.

A retried command never runs twice. If a response is lost, run the same command again. You get the stored result, with the note `This is the stored result of an earlier run`.

`steel browser stop` releases the session. A session that you do not stop ends at its timeout, or earlier when it gets no commands for a while. [Set timeouts](https://steel.dev/docs/sessions/timeouts#defaults) has the CLI's defaults. For a longer task, start the session first with a longer timeout in milliseconds. A timeout longer than 15 minutes needs a plan with longer sessions, as [Limits](https://steel.dev/docs/platform/limits#session-length) shows. This session can run for 30 minutes:

```sh
steel browser start --timeout 1800000
```

Change the inactivity timeout with `--inactivity-timeout` and a value in milliseconds, or pass `0` to turn it off.

## Scrape a page

`steel scrape` runs the [Scrape](https://steel.dev/docs/control/scrape) Quick action. It needs no session, and it prints the page as Markdown:

```sh
steel scrape https://example.com
```

Pass `--format` with a list of formats, such as `--format html,markdown`. Pass `--json` to print the full response. `steel screenshot` and `steel pdf` run the [Screenshot](https://steel.dev/docs/control/scrape#take-a-screenshot) and [PDF](https://steel.dev/docs/control/scrape#create-a-pdf) Quick actions:

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

Each command prints the URL of the file that Steel stored:

```text nocopy
https://images.steel.dev/v1/static/artifacts/TOKEN/FILE_NAME.png
https://files.steel.dev/v1/static/artifacts/TOKEN/FILE_NAME.pdf
```

## Use named sessions

Without `--session`, every `steel browser` command uses the session named `default`. Give each task its own name to run several sessions at the same time, from different shells or processes:

```sh
steel browser start --session checkout
steel browser open https://example.com --session checkout
steel browser snapshot -i --session checkout
steel browser stop --session checkout
```

Pass the same `--session` to every command of the task. A command with another name, or with none, works on another session.

`start` creates the session with options, such as `--proxy URL` (your own proxy), `--profile`, `--credentials` or `--timeout`. If the name already has a session, `start` releases it first and creates a new one.

`--session` also takes a session ID. Use it to drive a session that your code, the [MCP server](https://steel.dev/docs/control/mcp-server) or the dashboard created.

| Command | What it does |
| - | - |
| `steel browser sessions` | Lists the named sessions that are still live. |
| `steel browser live --session NAME` | Prints the session viewer URL, where you watch the [live view](https://steel.dev/docs/observability/live-view). |
| `steel browser stop --all` | Stops every session that this CLI started. Sessions that you attached to by ID are forgotten, not stopped. |

## Run against a self-hosted instance

The CLI also works with [Steel Browser](https://steel.dev/docs/self-hosting/steel-browser), which you run yourself. Steel Browser runs `steel browser` commands only when it starts with `ENABLE_COMMANDS_API=true`. Without it, the commands fail with `missing_capability`. See [Enable the Commands API](https://steel.dev/docs/self-hosting/configuration#enable-the-commands-api).

Pass your Steel Browser's API URL with `--api-url`:

```sh
steel browser open https://example.com --api-url https://steel.example.com/v1
```

The CLI picks the API URL in this order:

1. `--api-url`
2. `--local`: `browser.apiUrl` in `~/.config/steel/config.json`, or `http://localhost:3000/v1`
3. The `STEEL_API_URL` environment variable
4. The API URL that you signed in to with `steel login`, unless `STEEL_API_KEY` is set
5. `https://api.steel.dev/v1`

A URL on `steel.dev` is Steel Cloud, which needs your sign-in or an API key. The CLI treats any other URL as self-hosted.

To run Steel Browser on your machine with Docker, use the `steel dev` commands, then pass `--local`:

```sh
steel dev install
steel dev start
steel scrape https://example.com --local
steel dev stop
```

`steel dev start` does not set `ENABLE_COMMANDS_API`, so this instance runs `steel scrape`, `steel screenshot` and `steel pdf`, but not the `steel browser` commands.

## Check that it worked

Run `steel browser sessions` while you drive the browser. It lists the session named `default`, or the name that you passed with `--session`. Each command that worked exits with code `0`, so a script can check the exit code after each one. After `steel browser stop`, `steel browser sessions` no longer lists the session.

## Next steps

- [CLI commands](https://steel.dev/docs/reference/cli): Look up every command and its flags.
- [Commands](https://steel.dev/docs/control/commands): Read a page as a snapshot and act on its elements by ref, as `steel browser` does.
- [MCP server](https://steel.dev/docs/control/mcp-server): Give an MCP client the same browser tools without the CLI.
