Metadata-Version: 2.4
Name: silicon-browser
Version: 1.0.1
Summary: Terminal-native cloud browser CLI for AI agents.
Keywords: browser,automation,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: httpx>=0.28.1
Requires-Dist: playwright>=1.61.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.8
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/teamofsilicons/silicon-browser
Project-URL: Repository, https://github.com/teamofsilicons/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 through Browserbase. No local
Chromium, no stealth-patch maintenance: Silicon Browser gives you a fast,
scriptable CLI with a stable `@ref` element model and shareable remote-access
links.

## How it works

- Each named session is a cloud browser, driven over CDP via Playwright.
- The browser lives remotely 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/teamofsilicons/silicon-browser.git
# or:  pipx install git+https://github.com/teamofsilicons/silicon-browser.git
```

Or from a local clone:

```bash
git clone https://github.com/teamofsilicons/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, 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 <browserbase-api-key>
```

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 SILICON_BROWSER_API_KEY=<browserbase-api-key>   # or put it in a project-local .env file
# or:
export BROWSERBASE_API_KEY=<browserbase-api-key>
silicon-browser install        # verifies your key + connectivity
```

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

> Browserbase caps session/link lifetimes at 6 hours; Silicon Browser clamps
> higher requested values automatically and tells you when it does.

## Usage

```bash
silicon-browser open example.com         # start a 180-minute session and navigate
silicon-browser open example.com --timeout 60
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 file session upload ./data.csv
silicon-browser file input @e4 /tmp/.uploads/data.csv
silicon-browser file session archive
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> [--timeout min]` | Navigate (starts a session if none active; default 180 min) |
| `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 |
| `file session list\|upload\|download\|archive\|delete\|clear` | Manage files in the active browser session |
| `file global list\|upload\|download\|delete` | Not supported on Browserbase |
| `file input @ref /tmp/.uploads/name` | Set a file input to one or more session files |
| `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 |
| `proxy current\|status\|connect\|disconnect` | Inspect or change proxy routing |
| `close` | Release the cloud browser |
| `login [--key ...]` | Enter & save your provider API key (prompts if no `--key`) |
| `install` | Verify credentials |

### Files

Uploaded session files live inside the remote Browserbase VM under
`/tmp/.uploads`. Upload a local file into the current session, then bind it to a
web page file input:

```bash
silicon-browser snapshot -i
silicon-browser file session upload ./invoice.pdf
silicon-browser file input @e7 /tmp/.uploads/invoice.pdf
```

Browserbase downloads can be listed, downloaded by filename/id, or bundled into
a local archive:

```bash
silicon-browser file session list
silicon-browser file session download report.csv ./report.csv
silicon-browser file session archive ./session-files.zip
```

Provider-global file storage is not available on Browserbase.

### Global options

`--session/-s <name>` (parallel sessions) · `--profile <name>` ·
`--incognito` · `--proxy <url>` · `--location <country[-state][-city]>` ·
`--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 120 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 remote session timeout, so the expiry is enforced
server-side: when it elapses, Browserbase tears the browser down and the link stops
working. The default is **120 minutes** (clamped to Browserbase's maximum if higher).

- **Interactive** (default): recipients can click and type in the live browser.
- **View-only** (`--view-only`): the Silicon Browser interface renders the
  Browserbase live view without pointer events.

Because the provider 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 maps a local name to a Browserbase Context, so cookies, storage, and
login state persist 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
```

## Proxies

On Glass-managed silicons, proxy locations are resolved from Glass: assigned
browser profile location first, then team default. A session-scoped location
override is vpn-style and leaves the profile/default unchanged.

```bash
silicon-browser proxy status              # configured default/profile + session use
silicon-browser proxy current             # just the current session's proxy
silicon-browser proxy connect in-mumbai   # this session only
silicon-browser proxy disconnect          # back to profile/default routing
silicon-browser proxy set-location us-ny  # assigned profile, shared by its silicons
silicon-browser proxy set-default de      # profile-less fallback
```

## Configuration

| Variable | Purpose |
|---|---|
| `SILICON_BROWSER_API_KEY` / `BROWSERBASE_API_KEY` | Browserbase API key (required) |
| `SILICON_BROWSER_PROJECT_ID` / `BROWSERBASE_PROJECT_ID` | Optional Browserbase project id |
| `SILICON_BROWSER_BASE_URL` / `BROWSERBASE_BASE_URL` | Override the Browserbase API base URL |
| `SILICON_BROWSER_INTERFACE_URL` | Override the branded share-link host (default `https://browser.teamofsilicons.com`) |
| `SILICON_BROWSER_CONNECT_URL` | Legacy CDP connect-host override for old sessions |
| `SILICON_BROWSER_HOME` | State directory (default `~/.silicon-browser`) |

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

## License

Apache-2.0
