> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfsky.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Scrape pages and control a Surfsky cloud browser from a shell.

`surfsky` is a command-line client for the [Scraping API](https://docs.surfsky.io/quickstart/scraping_api.md) and for browser sessions. It suits one-off shell work and agents that run commands; for application code use an [SDK](https://docs.surfsky.io/sdk.md).

## Install

Requires Python 3.12 or newer.

```bash theme={null}
uv tool install surfsky-cli
```

`pipx install surfsky-cli` and `pip install surfsky-cli` work too.

## Credentials

Set your [API token and base URL](https://docs.surfsky.io/quickstart.md#before-you-start):

```bash macOS, Linux theme={null}
export SURFSKY_API_TOKEN='YOUR_API_TOKEN'
export SURFSKY_API_BASE_URL='YOUR_API_BASE_URL'
```

```powershell Windows theme={null}
$env:SURFSKY_API_TOKEN = 'YOUR_API_TOKEN'
$env:SURFSKY_API_BASE_URL = 'YOUR_API_BASE_URL'
```

Check them:

```bash theme={null}
surfsky status
```

The CLI does not store credentials. `--api-token` and `--base-url` override the environment.

## Scrape

```bash theme={null}
surfsky scrape https://example.com                         # Markdown
surfsky scrape https://example.com --only-main-content     # no navigation, footers or forms
surfsky scrape https://example.com -f markdown,links --json --pretty
surfsky scrape https://example.com -f screenshot -o shot.png
```

Formats are `markdown` (default), `html`, `raw_html`, `links` and `screenshot`. One format prints the content; several return JSON.

A plain `scrape` goes through the Scraping API and starts no session. `--profile ID`, `--keep` and the proxy and fingerprint flags (`--proxy`, `--country`, `--os`) start a browser for the scrape instead; `--keep` leaves it running and prints its session ID.

## Browser sessions

```bash theme={null}
surfsky session start
export SURFSKY_SESSION='returned-session-id'
surfsky goto https://example.com -s
surfsky click a -s
surfsky get text
surfsky screenshot -o page.png
surfsky session stop
```

`session start` prints the session ID. Export it as `SURFSKY_SESSION`, or pass `--session ID` to each command.

`-s` adds a snapshot of the page with `@N` references that `click`, `type` and `fill` accept; CSS selectors and `text=words` work too. Take a new snapshot after navigation: each one replaces the references.

A session is [billed](https://docs.surfsky.io/sessions.md#billing) until `surfsky session stop` or its idle timeout (`--idle-timeout SECONDS` on `session start`). `surfsky session list` shows what is running, and `surfsky session devtools` prints the [live view](https://docs.surfsky.io/screencast.md) and DevTools URLs.

To keep a login between runs, create a [persistent profile](https://docs.surfsky.io/sessions.md#persistent-profiles) and start sessions from it. Persistent profiles need a subscription plan; on pay-as-you-go `profile create` is refused.

```bash theme={null}
surfsky profile create acct --country us --os win
surfsky session start --profile PROFILE_ID
```

## Use it from an agent

Install the CLI's instructions for agents:

```bash theme={null}
surfsky skill --install
```

The command writes them to `.claude/skills/surfsky-cli/SKILL.md` and `.agents/skills/surfsky-cli/SKILL.md` in the current project. Run it again after upgrading the CLI.

For scripts, `--json` (or `SURFSKY_JSON=1`) returns `ok: true` on success and `ok: false` with `error.code`, `error.message`, `error.hint` and `error.retryable` on failure.

| Exit code | Meaning |
| - | - |
| 0 | Success |
| 1 | Error |
| 2 | Usage |
| 3 | Missing or expired session |
| 4 | Authentication |
| 5 | Timeout |
| 6 | Not found or stale reference |
| 7 | Quota, plan limit, rate limit or empty balance |

An agent host that speaks MCP can use the [MCP server](https://docs.surfsky.io/mcp-server.md) instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.