Metadata-Version: 2.4
Name: silicon-browser
Version: 0.1.1
Summary: Terminal-native browser CLI for AI agents, powered by Steel Browser.
Keywords: browser,automation,steel,cli,ai-agents,playwright
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Dist: playwright>=1.60.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: steel-sdk>=0.17.0
Requires-Dist: typer>=0.26.5
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/saket1225/silicon-browser
Project-URL: Repository, https://github.com/saket1225/silicon-browser
Description-Content-Type: text/markdown

# Silicon Browser

A terminal-native browser CLI for AI agents — same command surface as the
original [silicon-browser](https://github.com/unlikefraction/silicon-browser),
but every browser runs in the cloud on [Steel](https://docs.steel.dev). No local
Chromium, no stealth-patch maintenance: Steel provides the browser, fingerprinting,
proxies, and CAPTCHA solving; Silicon Browser gives you a fast, scriptable CLI on
top with a stable `@ref` element model and shareable remote-access links.

## How it works

- Each named session is a **Steel cloud browser**, driven over CDP via Playwright.
- The browser lives in Steel's cloud and persists between commands; Silicon Browser
  keeps a small local state file per session (`~/.silicon-browser/sessions/<name>.json`)
  recording the session id, active tab, and the last snapshot's `@ref → element` map.
- Every command opens a short-lived CDP connection, does its work, and disconnects.
  Disconnecting does **not** end the cloud browser — only `close` (or the session
  timeout) does.

## Install

Install directly from GitHub (no clone needed):

```bash
uv tool install git+https://github.com/saket1225/silicon-browser.git
# or:  pipx install git+https://github.com/saket1225/silicon-browser.git
```

Or from a local clone:

```bash
git clone https://github.com/saket1225/silicon-browser.git
cd silicon-browser
uv tool install .          # or: pipx install .
```

Then save your key — the easiest way is the `login` command, which prompts for
the key (hidden input), verifies it against Steel, and stores it persistently in
`~/.silicon-browser/config.env` (owner-only `0600`):

```bash
silicon-browser login          # prompts for your key, verifies & saves it
# or non-interactively:
silicon-browser login --key ste-...
```

Once saved, every command picks it up automatically — no need to re-export it.
Prefer environment variables? Those still work and take precedence:

```bash
export STEEL_API_KEY=ste-...   # or put it in a project-local .env file
silicon-browser install        # verifies your key + connectivity
```

Resolution order (first wins): `STEEL_API_KEY` env var → project-local `./.env`
→ saved `~/.silicon-browser/config.env`.

> Get a key at [app.steel.dev](https://app.steel.dev). Note that session/link
> lifetimes are capped by your Steel plan (e.g. 15 min on the hobby plan); Silicon
> Browser clamps to your plan's maximum automatically and tells you when it does.

## Usage

```bash
silicon-browser open example.com         # start a session and navigate
silicon-browser snapshot -i              # list interactive elements with @refs
silicon-browser click @e1                # click by ref
silicon-browser fill @e2 "hello"         # fill an input
silicon-browser type "search query"      # keystroke-level typing
silicon-browser get text @e3             # extract text / html / value
silicon-browser screenshot               # saved under ~/.silicon-browser/screenshots
silicon-browser evaluate "document.title"
silicon-browser tabs                     # list tabs
silicon-browser tab new example.org      # open / switch tabs
silicon-browser tab select 0
silicon-browser close                    # release the cloud browser
```

### Commands

| Command | Description |
|---|---|
| `open <url>` | Navigate (starts a session if none active) |
| `snapshot [-i] [--json]` | Accessibility tree with `@refs`; `-i` = interactive only |
| `click @ref` | Click an element |
| `fill @ref "text"` | Fill an input |
| `type "text" [--delay ms]` | Type at the keyboard level |
| `select @ref "value"` | Select a dropdown option |
| `hover @ref` | Hover an element |
| `scroll [down\|up\|top\|bottom] [--amount px]` | Scroll the page |
| `get text\|html\|value @ref` | Extract from an element |
| `screenshot [path] [--full-page]` | Capture a screenshot |
| `evaluate "js"` | Run JavaScript, print the result |
| `tabs` / `tab new [url]` / `tab select <n>` | Manage tabs |
| `share [--expiry min] [--view-only] [--new]` | **Remote access link** (see below) |
| `status` / `sessions` | Inspect sessions |
| `profile list\|save <name>\|delete <name>` | Persistent identities |
| `close` | Release the cloud browser |
| `login [--key ...]` | Enter & save your Steel API key (prompts if no `--key`) |
| `install` | Verify Steel credentials |

### Global options

`--session/-s <name>` (parallel sessions) · `--profile <name>` ·
`--incognito` · `--proxy <url>` · `--user-agent <ua>` · `--solve-captcha`

## Remote access links

Generate a shareable link to watch — or take control of — the live cloud browser:

```bash
silicon-browser share                      # interactive link, expires in 60 min
silicon-browser share --expiry 30          # custom expiry (minutes)
silicon-browser share --view-only          # watch only, no control
silicon-browser share --new --expiry 120   # fresh session dedicated to the link
```

The link's lifetime **is** the Steel session timeout, so the expiry is enforced
server-side: when it elapses, Steel tears the browser down and the link stops
working. The default is **60 minutes** (clamped to your plan's maximum if lower).

- **Interactive** (default): recipients can click and type in the live browser.
- **View-only** (`--view-only`): recipients can watch but not control.

Because Steel fixes a session's timeout at creation, `share` on an *existing*
session reports that session's real expiry; use `--new` to mint a fresh session
with exactly the expiry you ask for.

## Profiles

A profile saves a session's cookies + local/session storage + IndexedDB so identity
persists across sessions:

```bash
silicon-browser --profile work open github.com   # reuse saved context
silicon-browser --profile work close             # context is saved on close
silicon-browser profile list
```

## Configuration

| Variable | Purpose |
|---|---|
| `STEEL_API_KEY` | Your Steel API key (required) |
| `STEEL_BASE_URL` | Override the Steel API base URL (self-hosted Steel) |
| `STEEL_CONNECT_URL` | Override the CDP connect host (self-hosted Steel) |
| `SILICON_BROWSER_HOME` | State directory (default `~/.silicon-browser`) |

`silicon-browser login` writes `STEEL_API_KEY` to `$SILICON_BROWSER_HOME/config.env`
(default `~/.silicon-browser/config.env`, `0600`). Delete that file to "log out".

## License

Apache-2.0
