surfsky-cli 0.0.2__tar.gz

surfsky_cli-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5.0.1
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --all-groups
+      - run: uv run ruff check .
+      - run: uv run ty check
+      - run: uv run pytest -q

surfsky_cli-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5.0.1
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          python-version: "3.12"
+      - run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv sync --locked --all-groups
+      - run: uv run pytest -q
+      - run: uv build
+      - run: uv run --isolated --no-project --with dist/*.whl surfsky --version
+      - run: uv run --isolated --no-project --with dist/*.tar.gz surfsky --version
+      - run: uv publish

surfsky_cli-0.0.2/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.DS_Store

surfsky_cli-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surfsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

surfsky_cli-0.0.2/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: surfsky-cli
+Version: 0.0.2
+Summary: The Surfsky antidetect cloud browser from the terminal, for people and AI agents.
+Project-URL: Homepage, https://surfsky.io
+Project-URL: Documentation, https://docs.surfsky.io
+Project-URL: Repository, https://github.com/surfskyio/surfsky-cli
+Project-URL: Issues, https://github.com/surfskyio/surfsky-cli/issues
+Author: Surfsky SDK contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,antidetect,automation,browser,cli,scraping,surfsky
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.4
+Requires-Dist: beautifulsoup4>=4.9
+Requires-Dist: click>=8.2
+Requires-Dist: markdownify>=1.1
+Requires-Dist: pydantic>=2.8
+Requires-Dist: surfsky<0.1,>=0.0.6
+Description-Content-Type: text/markdown
+
+# surfsky-cli
+
+Command-line access to [Surfsky](https://surfsky.io)'s antidetect cloud browsers.
+Scrape pages, control browser sessions, and save logins in profiles.
+
+Requires Python 3.12+ on macOS, Windows, or Linux.
+
+## Install
+
+```sh
+uv tool install surfsky-cli
+```
+
+Or use `pipx install surfsky-cli` or `pip install surfsky-cli`.
+
+## Set up credentials
+
+Copy your API token and base URL from the [dashboard](https://app.surfsky.io).
+
+**Linux (bash)**
+
+```bash
+export SURFSKY_API_TOKEN='your-token'
+export SURFSKY_API_BASE_URL='your-base-url'
+surfsky status
+```
+
+**macOS (zsh)**
+
+```zsh
+export SURFSKY_API_TOKEN='your-token'
+export SURFSKY_API_BASE_URL='your-base-url'
+surfsky status
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:SURFSKY_API_TOKEN = 'your-token'
+$env:SURFSKY_API_BASE_URL = 'your-base-url'
+surfsky status
+```
+
+`--api-token` and `--base-url` override the environment variables. The CLI does
+not save credentials. Session records go in `~/.surfsky`; set `SURFSKY_HOME`
+to use another directory.
+
+## Scrape a page
+
+```sh
+surfsky scrape https://example.com                         # markdown
+surfsky scrape https://example.com --only-main-content     # omit navigation, footers, forms
+surfsky scrape https://example.com -f markdown,links --json --pretty
+surfsky scrape https://example.com -f screenshot -o shot.png
+surfsky scrape https://example.com --country us --proxy premium --os mac
+```
+
+Formats: `markdown` (default), `html` (cleaned), `raw_html` (unmodified),
+`links`, and `screenshot`. One format returns content; multiple formats return
+JSON. In text mode, `-f screenshot -o file.png` saves PNG bytes; screenshot
+output is otherwise base64.
+
+By default, `scrape` starts a browser and closes it when finished. Use `--keep`
+to leave it running and return its ID, or `--profile <uuid>` to use a saved
+profile. `--session <uuid>` (or `SURFSKY_SESSION`) reuses the active tab and
+navigates it to the URL. Omit the URL to read the current page.
+
+## Automate a browser
+
+```sh
+surfsky session start --proxy premium --proxy-type mobile --country us
+# prints <uuid>; pass it as --session <uuid> or export SURFSKY_SESSION=<uuid> once
+surfsky goto https://google.com --session <uuid>
+surfsky type 'textarea[name=q]' surfsky --session <uuid>
+surfsky press Enter -s --session <uuid>
+surfsky get text --session <uuid>
+surfsky screenshot -o results.png --session <uuid>
+surfsky session stop --session <uuid>
+```
+
+A unique prefix of the session ID is enough, and `--session` can go anywhere
+on the line.
+
+Proxy, location and fingerprint flags are the same as for `scrape`:
+`--proxy premium|shared|<url>`, `--country`, `--region`, `--city`,
+`--proxy-type mobile`, and `--os win|mac|android`. Look up codes with
+`surfsky proxy countries`, `surfsky proxy regions us`, and
+`surfsky proxy cities us texas`; `surfsky proxy quota` shows remaining traffic.
+
+`-s` returns a snapshot with references such as `[@11] combobox "Search"`.
+Use a reference from your own output as the target of `click`, `type`, or
+`fill`, for example `surfsky click @11`. CSS selectors and `text=words` also
+work. Take a new snapshot after navigation or a tab switch;
+each snapshot replaces the saved references.
+
+Sessions are billed per minute, including idle time, until stopped or closed
+by the idle timeout. Set the timeout with
+`surfsky session start --idle-timeout <seconds>`; see `--help` for the default.
+`surfsky status` reports the selected session's idle time and checks its
+connection, resetting the idle timer. `surfsky session devtools` prints live
+view and DevTools URLs.
+
+To reuse cookies across sessions:
+`surfsky profile create acct --country us --os win`, then
+`surfsky session start --profile <uuid>`.
+
+## Use with coding agents
+
+Run `surfsky skill --install` to install a Claude Code skill at
+`.claude/skills/surfsky/SKILL.md`. For other agents, `surfsky skill` prints the
+same instructions. The skill records the CLI version and includes upgrade
+instructions. After upgrading with `uv tool install surfsky-cli@latest`, run
+`surfsky skill --install` again to update it.
+
+- Use `--json` or `SURFSKY_JSON=1`. Success includes `ok: true`; errors include
+  `ok: false` and an `error` object with `code`, `message`, `hint`, and `retryable`.
+  JSON errors go to stdout; text errors go to stderr.
+- `-o <file>` saves output; `--pretty` indents JSON. For `screenshot`, `-o`
+  saves the PNG and `--json` returns its path and size.
+- Exit codes: 0 success, 1 error, 2 usage, 3 missing or expired session,
+  4 authentication, 5 timeout, 6 not found or stale reference, 7 quota or plan limit.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run pytest -q
+```

surfsky_cli-0.0.2/README.md

@@ -0,0 +1,128 @@
+# surfsky-cli
+
+Command-line access to [Surfsky](https://surfsky.io)'s antidetect cloud browsers.
+Scrape pages, control browser sessions, and save logins in profiles.
+
+Requires Python 3.12+ on macOS, Windows, or Linux.
+
+## Install
+
+```sh
+uv tool install surfsky-cli
+```
+
+Or use `pipx install surfsky-cli` or `pip install surfsky-cli`.
+
+## Set up credentials
+
+Copy your API token and base URL from the [dashboard](https://app.surfsky.io).
+
+**Linux (bash)**
+
+```bash
+export SURFSKY_API_TOKEN='your-token'
+export SURFSKY_API_BASE_URL='your-base-url'
+surfsky status
+```
+
+**macOS (zsh)**
+
+```zsh
+export SURFSKY_API_TOKEN='your-token'
+export SURFSKY_API_BASE_URL='your-base-url'
+surfsky status
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:SURFSKY_API_TOKEN = 'your-token'
+$env:SURFSKY_API_BASE_URL = 'your-base-url'
+surfsky status
+```
+
+`--api-token` and `--base-url` override the environment variables. The CLI does
+not save credentials. Session records go in `~/.surfsky`; set `SURFSKY_HOME`
+to use another directory.
+
+## Scrape a page
+
+```sh
+surfsky scrape https://example.com                         # markdown
+surfsky scrape https://example.com --only-main-content     # omit navigation, footers, forms
+surfsky scrape https://example.com -f markdown,links --json --pretty
+surfsky scrape https://example.com -f screenshot -o shot.png
+surfsky scrape https://example.com --country us --proxy premium --os mac
+```
+
+Formats: `markdown` (default), `html` (cleaned), `raw_html` (unmodified),
+`links`, and `screenshot`. One format returns content; multiple formats return
+JSON. In text mode, `-f screenshot -o file.png` saves PNG bytes; screenshot
+output is otherwise base64.
+
+By default, `scrape` starts a browser and closes it when finished. Use `--keep`
+to leave it running and return its ID, or `--profile <uuid>` to use a saved
+profile. `--session <uuid>` (or `SURFSKY_SESSION`) reuses the active tab and
+navigates it to the URL. Omit the URL to read the current page.
+
+## Automate a browser
+
+```sh
+surfsky session start --proxy premium --proxy-type mobile --country us
+# prints <uuid>; pass it as --session <uuid> or export SURFSKY_SESSION=<uuid> once
+surfsky goto https://google.com --session <uuid>
+surfsky type 'textarea[name=q]' surfsky --session <uuid>
+surfsky press Enter -s --session <uuid>
+surfsky get text --session <uuid>
+surfsky screenshot -o results.png --session <uuid>
+surfsky session stop --session <uuid>
+```
+
+A unique prefix of the session ID is enough, and `--session` can go anywhere
+on the line.
+
+Proxy, location and fingerprint flags are the same as for `scrape`:
+`--proxy premium|shared|<url>`, `--country`, `--region`, `--city`,
+`--proxy-type mobile`, and `--os win|mac|android`. Look up codes with
+`surfsky proxy countries`, `surfsky proxy regions us`, and
+`surfsky proxy cities us texas`; `surfsky proxy quota` shows remaining traffic.
+
+`-s` returns a snapshot with references such as `[@11] combobox "Search"`.
+Use a reference from your own output as the target of `click`, `type`, or
+`fill`, for example `surfsky click @11`. CSS selectors and `text=words` also
+work. Take a new snapshot after navigation or a tab switch;
+each snapshot replaces the saved references.
+
+Sessions are billed per minute, including idle time, until stopped or closed
+by the idle timeout. Set the timeout with
+`surfsky session start --idle-timeout <seconds>`; see `--help` for the default.
+`surfsky status` reports the selected session's idle time and checks its
+connection, resetting the idle timer. `surfsky session devtools` prints live
+view and DevTools URLs.
+
+To reuse cookies across sessions:
+`surfsky profile create acct --country us --os win`, then
+`surfsky session start --profile <uuid>`.
+
+## Use with coding agents
+
+Run `surfsky skill --install` to install a Claude Code skill at
+`.claude/skills/surfsky/SKILL.md`. For other agents, `surfsky skill` prints the
+same instructions. The skill records the CLI version and includes upgrade
+instructions. After upgrading with `uv tool install surfsky-cli@latest`, run
+`surfsky skill --install` again to update it.
+
+- Use `--json` or `SURFSKY_JSON=1`. Success includes `ok: true`; errors include
+  `ok: false` and an `error` object with `code`, `message`, `hint`, and `retryable`.
+  JSON errors go to stdout; text errors go to stderr.
+- `-o <file>` saves output; `--pretty` indents JSON. For `screenshot`, `-o`
+  saves the PNG and `--json` returns its path and size.
+- Exit codes: 0 success, 1 error, 2 usage, 3 missing or expired session,
+  4 authentication, 5 timeout, 6 not found or stale reference, 7 quota or plan limit.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run pytest -q
+```

surfsky_cli-0.0.2/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "surfsky-cli"
+version = "0.0.2"
+description = "The Surfsky antidetect cloud browser from the terminal, for people and AI agents."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["surfsky", "cli", "browser", "automation", "scraping", "antidetect", "agents"]
+authors = [{ name = "Surfsky SDK contributors" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "surfsky>=0.0.6,<0.1",
+    "click>=8.2",
+    "markdownify>=1.1",
+    "anyio>=4.4",
+    "pydantic>=2.8",
+    "beautifulsoup4>=4.9",
+]
+
+[project.scripts]
+surfsky = "surfsky_cli.main:main"
+
+[project.urls]
+Homepage = "https://surfsky.io"
+Documentation = "https://docs.surfsky.io"
+Repository = "https://github.com/surfskyio/surfsky-cli"
+Issues = "https://github.com/surfskyio/surfsky-cli/issues"
+
+[dependency-groups]
+dev = ["pytest>=8.3", "ruff>=0.6", "ty>=0.0.56"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml", ".github"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/surfsky_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 90
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.src]
+include = ["src"]

surfsky_cli-0.0.2/src/surfsky_cli/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("surfsky-cli")

surfsky_cli-0.0.2/src/surfsky_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+main()