sctl

English | 简体中文

sctl puts the browser you are using under the control of the command line, AI clients, and scripts. One cross-platform binary runs a local bridge daemon that reaches ScriptCat for userscript management and its own sctl Browser extension for tabs, browser data, page automation, and debugging.

Who decides: ScriptCat stays the authority for its scripts, so reading source and every write wait for approval in the browser. Running a background or scheduled script once, reading script logs, browser control, page automation, debugging, and raw CDP run immediately, by design; only deleting bookmarks and uninstalling an extension wait for approval, and other destructive commands need --yes. Read docs/threat-model.md before exposing sctl to anything you do not trust.

Features

• ScriptCat userscripts — list, read metadata and source (line windows, search), install, edit by content anchors, enable, disable, delete; run a background or scheduled script once and read script logs.
• Tabs and windows — list, open, close, activate, move, pin, mute, reload, duplicate, and group tabs across one or more paired browsers.
• Browser data — bookmarks, reading list, history, recently closed tabs, downloads, cookies, browsing data, and extensions.
• Page automation — accessibility snapshots with element refs, click, hover, fill, type, select, upload, scroll, navigate, wait, screenshot, and run JavaScript, in background tabs without switching the one you are on.
• Debugging — console messages, uncaught exceptions, browser messages, and network requests with headers and bodies.
• Raw CDP — send one Chrome DevTools Protocol command, or open an endpoint that Playwright connectOverCDP and Puppeteer connect attach to.
• One binary — JSON-RPC 2.0 over a mutually authenticated WebSocket, loopback by default; no Native Messaging host.

Install

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/scriptscat/sctl/main/scripts/install.sh | sh

Homebrew:

brew install scriptscat/tap/sctl

Windows PowerShell:

irm https://raw.githubusercontent.com/scriptscat/sctl/main/scripts/install.ps1 | iex

The install script verifies the release archive's sha256 and installs sctl into ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\sctl\bin (Windows). Pinning a version, manual downloads, and building from source are covered in docs/mcp.md.

Quick start

1. Start the daemon and leave it running:

   sctl serve              # in a terminal, or
   sctl service install    # in the background, starting at login

2. Pair the extensions. sctl connect prints a one-time code; each code pairs one extension, so run it once per extension.

   • ScriptCat: enable External Access in its options and enter the code.
   • sctl Browser: install it from the Chrome Web Store or Microsoft Edge Add-ons and enter a code in its popup. It needs Chrome 125 or newer (or a Chromium browser of that version). You can also load sctl-browser-extension-<version>.zip from GitHub Releases as an unpacked extension.

3. Check the connection:

   sctl status      # daemon and ScriptCat
   sctl scriptcats  # paired ScriptCat instances
   sctl browsers    # paired sctl Browser instances

Every sctl process must use the same data directory and listener address; the defaults work when they all run as the same user. The step-by-step guide, including SCTL_DATA_DIR, --listen-address, and the debugging infobar Chrome shows while a page is being driven, is docs/mcp.md.

Ways to use it

Command line. Every capability is a command; add -o json for scripts.

sctl tabs list
sctl page snapshot --tab 123
sctl debug console --tab 123 --level error
sctl get                      # ScriptCat scripts

Behavior, exit codes, and confirmations are in docs/cli.md.

AI clients over MCP. Configure the client to launch /absolute/path/to/sctl mcp --name my-ai-client. sctl mcp does not start the daemon. Client configuration, the tool reference, and troubleshooting are in docs/mcp.md.

Agent skill. To have an agent drive the command line instead of MCP, install the skill in skills/sctl/ with npx skills, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add scriptscat/sctl -g

npx skills check -g checks for updates and npx skills update -g installs them. When working on the skill itself, link it from a clone instead so edits apply immediately:

ln -s "$PWD/skills/sctl" ~/.claude/skills/sctl

Playwright and Puppeteer. sctl cdp endpoint prints addresses that existing scripts connect to, keeping the browser's logins; see docs/cli.md.

Commands

Group	What it does
sctl serve / connect / status / mcp	Run the daemon, pair an extension, show connection status, serve MCP over stdio.
sctl service	Run the daemon in the background as a user service (launchd, systemd, Task Scheduler).
sctl get / grep / install / edit / enable / disable / delete / run / logs	Manage ScriptCat userscripts, run a background or scheduled script once, and read script logs.
sctl scriptcats	List paired ScriptCat instances, or forget one.
sctl browsers	List paired sctl Browser instances, or forget one.
sctl tabs / windows / groups	Tabs, windows, and tab groups.
sctl bookmarks / reading-list	Bookmarks and the reading list.
sctl history / recent / downloads	History, recently closed tabs and windows, downloads.
sctl cookies / browsing-data / extensions	Cookies, browsing data, installed extensions.
sctl page	Automate a page: snapshot, click, fill, navigate, wait, screenshot, evaluate.
sctl debug	Record and read a tab's console and network requests.
sctl cdp	Send a raw CDP command, or open an endpoint for Playwright and Puppeteer.

sctl <command> --help lists every subcommand and flag; docs/cli.md is the full reference.

Documentation

• docs/cli.md — command-line reference.
• docs/mcp.md — installation, pairing, MCP client setup, and the MCP tool reference.
• docs/threat-model.md — what sctl protects and what it deliberately does not.
• docs/README.md — index of the contributor docs (architecture, protocol, development).

License

GPL-3.0, the same license as ScriptCat. See LICENSE.