Skip to main content
surfsky is a command-line client for the Scraping API and for browser sessions. It suits one-off shell work and agents that run commands; for application code use an SDK.

Install

Requires Python 3.12 or newer.
pipx install surfsky-cli and pip install surfsky-cli work too.

Credentials

Set your API token and base URL:
Check them:
The CLI does not store credentials. --api-token and --base-url override the environment.

Scrape

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

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 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 and DevTools URLs. To keep a login between runs, create a persistent profile and start sessions from it. Persistent profiles need a subscription plan; on pay-as-you-go profile create is refused.

Use it from an agent

Install the CLI’s instructions for agents:
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. An agent host that speaks MCP can use the MCP server instead.