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.
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
| Command | What it does |
|---|---|
open URL | new unfocused window; prints the tab id |
eval TAB JS | evaluate JavaScript in the page (promises are awaited), result as JSON |
click TAB JS | scroll an element into view and send a real mouse click to its centre |
type TAB TEXT, key TAB KEY | type 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.png | screenshot of the tab |
tabs, close, detach | list 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
- No second browser to log in to, no copied cookies, no separate test profile.
- 2FA and "new device" checks are already done in the browser you use.
- Jobs run in background windows and tabs and pages are told they have focus, so you can keep typing elsewhere.
- Several Chrome profiles are supported: load the extension in each and name the one you want.
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.
Chrome or Chromium, Python 3.10+, macOS and Linux. Source on GitHub.