chromix-too

Chromix-Too

This project provides external (e.g. command-line or scripted) access to Chrome's internal (Javascript) API's.

For example, the following command closes all tabs on stackoverflow:

chromix-too rm stackoverflow.com

Chromix-too is a replacement for chromix. Chromix-too is considerably simpler, uses a Unix-domain socket for communication between client and server (which is more secure), and is better packaged (it can be used as a module too).

Getting started

There are three components: a chrome extension, a server and the chromix-too utility.

Install the extension from the Chrome Store.

To install the server and the chromix-too utility:

sudo npm install -g chromix-too

Next, you need to run the server:

chromix-too-server

And try out the client:

chromix-too ls

Of course, you need to keep the server running all the time. There are many ways to do this, but I use daemontools; my daemontools run file is just:

PATH="/usr/local/bin:$PATH"
HOME='/home/blott' exec setuidgid blott chromix-too-server

(Or perhaps just leave the server running in a tmux session.)

Commands

List tabs:

chromix-too ls

List just tab Ids:

chromix-too tid

Focus a tab:

chromix-too focus https://github.com/smblott-github/chromix

Select a tab (select the tab but don't focus Chrome window):

chromix-too select https://github.com/smblott-github/chromix

Remove a tab:

chromix-too rm https://github.com/smblott-github/chromix

Reload a tab:

chromix-too reload https://github.com/smblott-github/chromix

Open a tab:

chromix-too open https://github.com/smblott-github/chromix

View a file:

chromix-too file ./README.html

(The file command also focuses and reloads an existing tab if one exists.)

Verify that everything is running correctly:

chromix-too ping

Raw JSON

Call any available Chrome function from the command line:

chromix-too raw chrome.storage.local.set '{"pi": 3.141}'

chromix-too raw chrome.storage.local.get pi
# {"pi":3.141}

chromix-too raw chrome.storage.local.get pi | jq '.pi'
# 3.141

Filters

For all of the commands above (except where it doesn't make sense), you can filter the list of tabs to which the command applies.

There are three kinds of filter:

1. If the filter is just a bare number, then it is interpreted as a tab Id.

2. If the filter is one of the boolean options described here, then the corresponding flag is set. For example, you can use pinned to operate on all pinned tabs.

   These boolean flags can be inverted: -pinned selects all unpinned tabs.

3. Any remaining filter arguments are treated as queries. Tabs are removed from consideration unless the query text is present in either the tab's URL or the tab's title.

Examples:

# Remove the tab with this tab Id.
chromix-too rm 1234

# Remove all audible tabs.
chromix-too rm audible

# Remove all unpinned tabs.
chromix-too rm -pinned

# List GMail tabs.
chromix-too ls mail.google.com

# Focus my Google Inbox tab.
chromix-too focus Inbox [e-mail]

All commands which accept filters fail (so, yield a non-zero exit status) if there are no matching tabs.

Usage as a module

It is also possible to use chromix-too as a node module; here's an example:

chromix = require("chromix-too")().chromix

chromix "chrome.storage.local.set", {}, {pi: 3.141}, ->
  chromix "chrome.storage.local.get", {}, "pi", (response) ->
    console.log response.pi

The second argument ({}, here) is a place holder for future extensions.

The general form is:

chromix PATH, REQUEST, ARGS..., CALLBACK

The number of ARGS... provided must match the number of (non-callback) arguments expected by the relevant Chrome API call. When the call is actually made, chromix-too simply appends its own callback, and that callback must be in the correct argument position.

Known issues

• There is currently no way to set the websocket port used between the Chrome extension and the server.
• Only background-page API calls are possible. It is intended to add the ability to invoke functions in a content script at some point in the future.

Contributions are welcome.