Tabrelay

Tabrelay / Control Chrome from the command line

Control your logged-in Chrome from the command line

Most browser automation starts a fresh browser that knows nothing about you. Tabrelay does the opposite: a shell command drives the Chrome you already use, with your profile, cookies, logins and 2FA.

Download Tabrelay - free, MIT

Chrome or Chromium, Python 3.10+, macOS and Linux. Source on GitHub.

How it works

Tabrelay has two parts: a single-file Python command, and a small Chrome extension. The command sends jobs over 127.0.0.1:47833 to the extension. The extension carries them out with the Chrome DevTools Protocol, through Chrome's chrome.debugger extension API, in the profile where it is installed.

tabrelay (Python) -> 127.0.0.1:47833 -> Tabrelay extension (Chrome) -> CDP -> the page

Python 3.10 or newer with only the standard library is needed. There is no build step and no npm. It is used on macOS and Linux.

A first session in the shell

tabrelay ping                      # starts the local server if needed, waits for the extension
TAB=$(tabrelay open https://example.com/)   # a new background window; prints the tab id
tabrelay eval "$TAB" 'document.title'       # "Example Domain"
tabrelay click "$TAB" 'document.querySelector("a")'
tabrelay shot "$TAB" /tmp/example.png
tabrelay close "$TAB"

Every action is a command that prints plain text or JSON and exits non-zero on error, so it works from a shell script, cron or any program that can run a command.

The commands

CommandWhat it does
open URLnew unfocused window; prints the tab id
eval TAB JSevaluate JavaScript in the page (promises are awaited), result as JSON
click TAB JSscroll an element into view and send a real mouse click to its centre
type TAB TEXT, key TAB KEYtype into the focused element; press Enter, Tab, Escape and others
file TAB JS PATH...set the files of an <input type=file>
shot TAB FILE.pngscreenshot of the tab
tabs, close, detachlist allowed-site tabs, close one, stop debugging

Write your own script in Python

tabrelay.py is also a module: evaluate, wait_for, click, fill_lines (for rich editors such as contenteditable and ProseMirror), set_files, shot and raw cdp calls give you what you need to script a site you are logged in to.

Why use your own Chrome

For how this compares to Playwright and Puppeteer, read Playwright and Puppeteer with a logged-in Chrome. If an AI agent will run the commands, read browser automation for AI agents.

Install and the allow-list

Tabrelay is not on the Chrome Web Store; you load it unpacked. Download the tarball from the latest release, run ./bin/tabrelay config once to create the local token, open chrome://extensions, turn on Developer mode, click Load unpacked and choose the extension/ folder. Then add the domains your scripts need on the extension's options page. The extension only acts on sites on that list.

Frequently asked questions

Does Tabrelay need Chrome to be started in a special way?

No. You load the extension in your normal Chrome. There is no remote debugging port to open, and no automation profile.

Does it work on Windows?

The core has no OS-specific code, so Windows should work, but it is untested. macOS and Linux are what it is used on.

Can it run headless or on a server?

No, that is not what it is for. Use Playwright or Puppeteer for headless and server work.

Does it work in Firefox or Safari?

No. They do not have chrome.debugger. Chrome is regularly used; other Chromium browsers probably work if they support unpacked MV3 extensions and chrome.debugger.

Why does Chrome show "started debugging this browser"?

That is Chrome being honest about the debugger permission while Tabrelay works on a tab. tabrelay detach removes it when you are done.

Download Tabrelay - free, MIT

Chrome or Chromium, Python 3.10+, macOS and Linux. Source on GitHub.