Skip to content

URL scheme

The BenchBar app answers benchbar:// links. Anything that can open a URL can drive a bench with them: Raycast, Shortcuts, Alfred, a shell script with open, a bookmark in the browser.

open "benchbar://up?bench=frappe-bench"

The app has to be installed (it registers the scheme); if it is not running, the link starts it first.

Routes

LinkWhat it does
benchbar://upstarts the bench, like benchup
benchbar://downstops the bench, like benchdown
benchbar://restartrestarts the bench, like benchrestart
benchbar://openopens the site in the browser
benchbar://logsopens the bench’s log window
benchbar://windowopens the BenchBar window at the bench’s page
benchbar://doctorruns doctor and opens the bench’s Health tab
benchbar://consoleTerminal with benchbar console for the site
benchbar://dbTerminal with benchbar db for the site
benchbar://editorthe bench folder in VS Code or Cursor (the one chosen in Settings)

There is no route for Open as (signing in as another user): any web page can open a benchbar:// link, and a page you visit must not be able to change who you are signed in as. Raycast and Shortcuts can run benchbar open --as USER instead, once you turned Open as on for the site.

Start and restart check ports first, as the buttons do: a conflict is not resolved from a link, it shows in the popover.

Which bench

QueryMeaning
bench=NAMEthe bench with this name, as benchbar list shows it
bench=/absolute/paththe bench in this folder; ~/frappe-bench works too
site=NAMEwith open, console and db: this site instead of the default one

Without bench=, a link acts on the bench selected in the menu bar, or on the only bench there is. When that is not clear (several benches and none selected, two benches with the same name, a name or site that does not exist), the link does nothing and the BenchBar window opens with a message that says why. benchbar://window without a bench just opens the window.

Examples:

benchbar://restart?bench=frappe-bench
benchbar://open?bench=v16-bench&site=v16two
benchbar://doctor?bench=%2FUsers%2Fyou%2Fwork%2Ffrappe-bench

Encode a path in a query: / becomes %2F, a space %20.

LinkWhat it does
benchbar://share/FINGERPRINT/appOpens the joined room’s site in your browser through the local forwarder. A room you have not joined only shows On your network
benchbar://share/join?...The join sheet, filled in from the invite. It waits for your click and never joins by itself

FINGERPRINT is the first 16 hex characters of the room’s pinned certificate fingerprint: it names a room, it is not a secret. The first link opens a room you already joined without asking, like benchbar://open. BenchBar logs only “share link”, never the address.

Two links share a team profile. They need no bench.

LinkWhat it does
benchbar://profile/import?url=ENCTeam Profiles with the Import sheet filled in with this https address
benchbar://profile/subscribe?url=ENCTeam Profiles with the Subscribe sheet filled in with this git repository

ENC is the address, percent encoded. The sheet waits for your click: Review fetches and checks the profile, Add Profile saves it, Subscribe clones the repository. Nothing is installed from a link. Import takes only an https address, subscribe only an https, ssh or git@host:owner/repo remote; any other address opens the window with a message instead. Export in Team Profiles makes an import link for you (Copy Import Link).

Any web page can open a benchbar:// link, so links only start, stop, restart and open things. console and db only open a Terminal window at a prompt; nothing runs in it until you type. There is no route for repair, install, update, pull, restore, dropping a site or anything else that changes or deletes files; the profile links only fill in a sheet, and the app ignores any route not in the tables above and logs it. Browsers ask before a page opens an app, so a page cannot do even that silently.

To see ignored links, stream the app’s log:

log stream --predicate 'subsystem == "com.akashmishra.benchbar" && category == "url"'

Raycast

A script command per action. Save it in your script commands folder, for example ~/raycast/benchup.sh, and make it executable:

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Start Frappe bench
# @raycast.mode silent
# @raycast.packageName BenchBar
open "benchbar://up?bench=frappe-bench"

An argument makes one command for every bench:

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Restart bench
# @raycast.mode silent
# @raycast.packageName BenchBar
# @raycast.argument1 { "type": "text", "placeholder": "bench name" }
open "benchbar://restart?bench=$1"

A Raycast Quicklink with the link as its URL works too, without a script.

Shortcuts

  1. Create a shortcut and add the URL action with the link, for example benchbar://up?bench=frappe-bench.
  2. Add Open URLs after it.
  3. Give the shortcut a keyboard shortcut in its details, or add it to the menu bar.

A Choose from Menu action in front with Start, Stop and Restart, each leading to its own URL, makes one shortcut for all three.