Skip to content

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-app
benchbar install # sets up this Mac: asks for sudo once
source ~/.zshrc && benchup

The 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/benchbar

The 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 | bash

The 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:

  1. It checks macOS and Apple Silicon (it warns on Intel), the Xcode Command Line Tools (it offers xcode-select --install and waits) and Homebrew (it offers the official installer).
  2. It clones the CLI into ~/.local/share/benchbar, or pulls when the clone exists, links benchbar and frappe-mac into ~/.local/bin, and adds that folder to PATH in ~/.zshrc inside a # >>> benchbar-path >>> marker block.
  3. It installs or updates the BenchBar app from the latest GitHub release: the zip is checked against the release’s SHA256SUMS and unpacked into ~/Applications. This step is skipped when no release exists yet.
  4. It offers benchbar adopt for a bench it finds, or benchbar 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 | bash

It 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.

FlagWhat it does
--yesAccept 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-runPrint the plan and every command, change nothing
--no-appThe CLI only
--app-onlyThe app only
--version vX.Y.ZInstall that release of the app instead of the latest. On Linux: check out that release of the CLI
--uninstallRemove 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:

  1. 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.
  2. Open System Settings > Privacy & Security, scroll to the Security section: “BenchBar was blocked to protect your Mac”.
  3. 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 start
brew install xcodegen
scripts/release-local.sh # the app: dist/BenchBar-<version>.zip and .dmg
scripts/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 install

install 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 | iex

This 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 upgrade

    The 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 upgrade leaves 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 installer
benchbar self-update --check # this version against the latest release

or, 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 -- --yes

It 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.

  1. Install with Homebrew:

    brew install askysh/tap/benchbar askysh/tap/benchbar-app
  2. Run Homebrew’s repair by its full path. In this Terminal ~/.local/bin still leads to the old copy, so plain benchbar would run that one:

    /opt/homebrew/opt/benchbar/bin/benchbar repair

    It moves the state to ~/.local/state/benchbar, points the ~/.local/bin links at Homebrew’s CLI and rewrites the helper block in ~/.zshrc.

  3. Run source ~/.zshrc, or open a new Terminal tab.

  4. Later, move ~/.local/share/benchbar and ~/Applications/BenchBar.app to 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.

The first run wizard's Welcome page

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 start in 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/state is 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 --all
brew uninstall --cask benchbar-app
brew uninstall benchbar

Run 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-run
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bash -s -- --uninstall

It 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 folder

It 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.