Install
There are four ways in. Homebrew installs the CLI and the app together
and is the one most people want. The one line installer does the same
without Homebrew’s formula and cask. The DMG gives you the app, which
carries its own copy of the CLI but puts no benchbar command in
Terminal. Building from source is for contributors.
Check the requirements first: macOS 14 or later on Apple Silicon, Homebrew and the Xcode Command Line Tools, about 5 GB of free disk. On Linux and Windows, see Linux and Windows.
Homebrew
brew install askysh/tap/benchbar askysh/tap/benchbar-appbenchbar install # sets up this Mac: asks for sudo oncesource ~/.zshrc && benchupThe first line installs the CLI, the benchbar formula, and the menu bar
app, the benchbar-app cask, from the askysh/tap tap. Type both names:
Homebrew trusts a third party tap only for the names you type, so the
cask alone cannot pull in its formula. benchbar install sets up the
bench, the site and the background service as in the
Quick start; with a bench you already have, run
benchbar adopt instead. To check a Mac before installing, without a
bench, run benchbar doctor --prerequisites (Apple Silicon, macOS 14,
Command Line Tools, Homebrew, free disk, the bench folder, cleanup tools
and the default ports; each check that is not ok names its fix). The BenchBar app drives install and adopt
through --json --yes, which prints one JSON event per line; the format
is in the JSON API.
The cask needs Apple Silicon and macOS Sonoma or later. For the CLI alone, on an Intel Mac too:
brew install askysh/tap/benchbarThe CLI keeps its state (the remembered benches, per bench settings, the
logs and backups of every run) in ~/.local/state/benchbar, outside
Homebrew’s folders, so brew upgrade and brew cleanup never touch it.
benchbar where shows how the CLI was installed and where its state is.
The one line installer
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bashThe installer checks macOS, the Command Line Tools and Homebrew, clones
the CLI into ~/.local/share/benchbar with links in ~/.local/bin, adds
that folder to ~/.zshrc, and installs the BenchBar app from the latest
release into ~/Applications after checking its sha256. It then offers
benchbar adopt for a bench it finds, or benchbar install. The
installer itself never runs sudo. It leaves to Homebrew what Homebrew
installed: with the benchbar formula it skips the CLI, with the
benchbar-app cask the app, and prints the brew command instead.
In more detail, in this order, and it says so before each step:
- It checks macOS and Apple Silicon (it warns on Intel), the Xcode
Command Line Tools (it offers
xcode-select --installand waits) and Homebrew (it offers the official installer). - It clones the CLI into
~/.local/share/benchbar, or pulls when the clone exists, linksbenchbarandfrappe-macinto~/.local/bin, and adds that folder toPATHin~/.zshrcinside a# >>> benchbar-path >>>marker block. - It installs or updates the BenchBar app from the latest GitHub
release: the zip is checked against the release’s
SHA256SUMSand unpacked into~/Applications. This step is skipped when no release exists yet. - It offers
benchbar adoptfor a bench it finds, orbenchbar install.
The installer never runs sudo itself. Homebrew’s own installer, if
you accept it in step 1, asks for your password and says so first. If
you accept benchbar install or benchbar adopt in step 4, that
command asks for it once too, for the /etc/hosts line and the
wkhtmltopdf package. Prompts read from the terminal, so the installer
works when piped from curl.
The installer on Linux
The same line works on Ubuntu 24.04 and in WSL. It installs the command line tool only, since there is no app on Linux:
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bashIt needs git; when git is missing it stops and prints
sudo apt update && sudo apt install -y git. It never runs sudo. It
clones the CLI into ~/.local/share/benchbar (or pulls), links
benchbar into ~/.local/bin and adds that folder to PATH in
~/.bashrc (~/.zshrc when your login shell is zsh) inside the same
# >>> benchbar-path >>> block. It asks nothing, with or without a
terminal, and BENCHBAR_NONINTERACTIVE=1 says so explicitly. It then
prints the next step: open a new terminal and run benchbar install. In
WSL it adds that the BenchBar tray on Windows can continue the setup.
--version vX.Y.Z checks out that release of the CLI instead of main
(a detached checkout; a run without it goes back to main). --dry-run
and --uninstall work as on a Mac; --app-only is refused.
Installer flags
Pass flags after bash -s --, for example
curl -fsSL .../install.sh | bash -s -- --no-app.
| Flag | What it does |
|---|---|
--yes | Accept every default, no questions (no terminal needed). On a Mac that already has the CLI in ~/.local/share/benchbar this is an update: the CLI and the app only, no bench is adopted or installed and the Homebrew installer is never run |
--dry-run | Print the plan and every command, change nothing |
--no-app | The CLI only |
--app-only | The app only |
--version vX.Y.Z | Install that release of the app instead of the latest. On Linux: check out that release of the CLI |
--uninstall | Remove the app, the links and the PATH block; see Uninstall |
The app from the DMG
Download BenchBar-<version>.dmg from the
releases page, open it and
drag BenchBar to Applications. Since 0.6.1 the app and the DMG are
signed with a Developer ID, notarized by Apple and stapled, so BenchBar
opens like any other download, and later versions arrive through
Check for Updates… (Sparkle). Verify a download with
shasum -a 256 -c SHA256SUMS from the same release.
Since 0.7.1 the app carries its own copy of the CLI and runs it, so its
buttons work without anything else. For benchbar and the bench*
helpers in Terminal, add the CLI too: brew install askysh/tap/benchbar,
or the one line installer with --no-app. Either one hands off to the
app’s CLI once the app is in /Applications or ~/Applications (an app
run straight from the DMG does not register its CLI), see
Updating.
Releases before 0.6.1
Releases up to 0.6.0 were not signed with an Apple Developer ID, and macOS 15 and later stopped their first launch:
- Double click BenchBar. A dialog says “BenchBar” Not Opened: Apple could not verify it is free of malware. Click Done. The highlighted button is Move to Trash (Move to Bin in British English), so do not press Return.
- Open System Settings > Privacy & Security, scroll to the Security section: “BenchBar was blocked to protect your Mac”.
- Click Open Anyway, confirm with your password or Touch ID, then Open Anyway once more.
This happened once per install. The one line installer avoided it,
because curl sets no quarantine flag on the download.
From source
The CLI runs straight from the clone. Building the app needs full Xcode 26 or newer, not only the Command Line Tools.
git clone https://github.com/askysh/benchbar.git && cd benchbar./benchbar install # optional: sets up a bench and a site, as in the Quick startbrew install xcodegenscripts/release-local.sh # the app: dist/BenchBar-<version>.zip and .dmgscripts/macos-install-local.sh # or build it and copy it to ~/Applications./benchbar install is the full setup: Homebrew packages, a bench, a
site and the background service. It asks for passwords and sudo, and
the first run takes a while. Skip it when you only want to work on the
app or adopt a bench you have.
Linux
From 0.8 the same CLI runs on Linux: Ubuntu 24.04 and other Debian based systems with apt, Windows through WSL first, with the v15-lts profile so far. There is no menu bar app on Linux; on Windows a tray app shows the benches of the distro: see Windows.
git clone https://github.com/askysh/benchbar.git && cd benchbar./benchbar installinstall runs 00-linux-system-deps.sh: MariaDB and Redis from apt,
Python from uv, Node from fnm, the pinned wkhtmltopdf .deb, and
libnss-myhostname so *.localhost names resolve. It asks for sudo
once up front and not at all on a second run. Each bench runs as its own
systemd --user unit, and loginctl enable-linger brings a running
bench back after a reboot. The default site is linuxdev.localhost, and
benchbar never edits /etc/hosts there. The bench* helpers go to
~/.bashrc. benchbar doctor --prerequisites on Linux checks, without a bench and
without sudo: the distro (Ubuntu 24.04 is tested, others warn), the CPU
(x86_64 is needed for the PDF package), that you are not root, sudo (your
user is in the sudo group), apt, systemd, linger, memory, free disk, the
bench folder, the default ports and the MariaDB root password state. Each
check that is not ok names its fix.
install first checks that ports 3306 (MariaDB) and 6379 (the system
Redis) are free, or held by this distro’s own services. In WSL 2 every
distro shares one network, so only one of them can run MariaDB. When
another distro or program holds the port, the plan lists it as a blocker
and the run stops before it asks for sudo, with error id
port_3306_in_use (or port_6379_in_use) and the fix: stop MariaDB in
the other distro (sudo systemctl stop mariadb), or install in that
distro. benchbar stops nothing for you.
After the install, run source ~/.bashrc (or open a new terminal), then
benchup. The helpers are in ~/.bashrc, not in ~/.zshrc.
Windows
A beta. The benches run inside WSL 2, with the same CLI as on Linux. In PowerShell, as yourself, without administrator rights:
irm https://raw.githubusercontent.com/askysh/benchbar/main/install.ps1 | iexThis installs benchbar.exe, which forwards every command to the
distro, and BenchBar Tray, the notification area app. It checks the zip
against its SHA256, puts the folder on your PATH, adds a Start menu
shortcut, starts the tray and ends with benchbar.exe doctor. Run it
again to update. On our Windows 11 test PC it showed no SmartScreen
warning. The Windows programs are not signed yet, and Smart App Control
blocks unsigned programs: when it is on, the installer stops first and
says what to do (see
Before you install). Every release has
SHA256SUMS and, from the next release, build provenance you can verify
(see Signing and verification).
When the tray starts and finds no bench, its
first run wizard checks the PC and sets up WSL,
the Linux distro, the bench and the keepalive. Windows has
the requirements, what Windows may show, the flags, the tray, Report a
Bug, uninstall (-Uninstall) and how to verify a download.
Updating
BenchBar.app carries its own copy of the CLI, and since 0.7.1 Homebrew’s
and the one line installer’s benchbar hand off to it once the app is
installed: whichever benchbar you run, it is the app’s version. So with
the app, updating the app updates everything, by either channel:
-
In the app: Update Now (or Check for Updates… in the menu bar menu). Sparkle downloads the new version and restarts BenchBar. Your benches keep running.
-
With Homebrew, when the cask installed the app:
brew upgradeThe cask has
auto_updates, so brew replaces the app only when the app itself is older than the tap’s version: after Sparkle updated it,brew upgradeleaves it alone, and when Sparkle has not, brew updates it. Right after a release the tap can be a few minutes behind.
benchbar where shows which CLI runs (install app) and which one it
was handed off from. To run Homebrew’s or the installer’s own copy for
once, set BENCHBAR_NO_HANDOFF=1. A git checkout of your own never
hands off.
Without the app
Homebrew’s CLI updates with brew upgrade askysh/tap/benchbar, which
benchbar self-update runs after asking. The one line installer’s CLI
updates with benchbar self-update:
benchbar self-update # shows the plan, asks, then runs the installerbenchbar self-update --check # this version against the latest releaseor, on any version, including 0.5.x, which has no self-update:
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bash -s -- --yesIt pulls the CLI in ~/.local/share/benchbar, replaces the app in
~/Applications (it quits a running BenchBar first), and changes no
bench: it never adopts, installs or updates a bench and never runs
bench update. It never runs sudo. An app in /Applications is
replaced there when that folder is writable (the app and self-update
pass BENCHBAR_APP_DIR=/Applications).
The pull is a fast forward only: local changes in
~/.local/share/benchbar stop it with a message instead of being
overwritten. After an update, run benchbar doctor: when it says the
runner is outdated, benchbar repair rewrites it, and a running bench
picks it up on its next start.
If your benchbar is a git checkout of your own, for example
~/dev/benchbar, self-update updates only the app (--app-only) and
tells you to update the CLI with git pull in that checkout.
From the one line installer to Homebrew
Your benches keep running through the move: their agents and runners never name the CLI.
-
Install with Homebrew:
brew install askysh/tap/benchbar askysh/tap/benchbar-app -
Run Homebrew’s
repairby its full path. In this Terminal~/.local/binstill leads to the old copy, so plainbenchbarwould run that one:/opt/homebrew/opt/benchbar/bin/benchbar repairIt moves the state to
~/.local/state/benchbar, points the~/.local/binlinks at Homebrew’s CLI and rewrites the helper block in~/.zshrc. -
Run
source ~/.zshrc, or open a new Terminal tab. -
Later, move
~/.local/share/benchbarand~/Applications/BenchBar.appto the Trash.
Do not use install.sh --uninstall for this: it stops every bench’s
agent. Until the old copies are gone, doctor’s “Second CLI” and
“BenchBar.app copies” warnings point at them. Two copies of the app
matter more than two of the CLI: the login item and Spotlight may open
the old one, and its CLI is the one every benchbar hands off to.
After installing
Open a new Terminal tab, or run source ~/.zshrc, so benchbar and the
bench* helpers are on your PATH. Then follow the
Quick start, or open BenchBar: on a Mac with no bench
its window starts the first run wizard.

Uninstall
Uninstalling removes BenchBar, not your benches: every bench, site, database and the Homebrew packages they use stay. Two things are worth knowing first:
- Removing a bench’s agent stops that bench. Without the agent it no
longer runs in the background; you can still run it by hand with
bench startin its folder. - The logs and file backups of every benchbar run, the remembered
benches and the settings benchbar keeps for each bench are in
~/.local/state/benchbar, for Homebrew and the one line installer alike. Uninstalling keeps that folder; move it to the Trash yourself when you no longer want them. When~/.local/stateis on another volume than~/.local/share/benchbar, the state stays in that checkout’s.benchbar/folder, and deleting the checkout deletes it.
Homebrew
benchbar uninstall-service --allbrew uninstall --cask benchbar-appbrew uninstall benchbarRun uninstall-service --all first: brew uninstall cannot stop the
background agents. It asks once, then stops every bench that has a
benchbar agent and removes its agent, runner and Procfile.lean, and the
# >>> benchbar >>> block from ~/.zshrc.
The one line installer
To see the plan without changing anything, then to uninstall:
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bash -s -- --uninstall --dry-runcurl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bash -s -- --uninstallIt removes the app, the benchbar and frappe-mac links and the PATH
block. Then it asks, for each bench’s agent, whether to stop the bench
and remove its agent, runner and Procfile.lean, and last whether to
delete the checkout. Answer no to keep either. With --yes the answer
to both is yes. When ~/.local/state/benchbar is a link into the
checkout, the checkout is kept even with --yes, and the run says to
move the state first.
One bench
To remove only the background service of one bench and keep BenchBar:
benchbar uninstall-service --bench-dir ~/frappe-bench # use your bench's folderIt stops the bench and removes its agent, runner and Procfile.lean.
It also removes the # >>> benchbar >>> block from ~/.zshrc, so
benchup and the other helpers are gone for every bench until
benchbar repair on a remaining bench writes the block again.
benchbar never deletes a whole bench. The only commands that drop or
overwrite a site’s database, benchbar site drop and benchbar pull --replace, back it up first. To wipe a bench by hand, see
Troubleshooting.