Testing BenchBar on your Mac
Thanks for trying BenchBar. This takes about ten minutes if you already
have a bench, longer for a fresh install (Homebrew downloads and
bench init do most of the waiting). Three steps: install, try it, send
a report.
You need macOS 14 or later on Apple Silicon, Xcode Command Line Tools and Homebrew. The installer checks all of that and tells you what is missing.
1. Install
One line, in Terminal:
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bashIt clones the CLI into ~/.local/share/benchbar, links benchbar into
~/.local/bin, adds that folder to your ~/.zshrc, and installs the
BenchBar menu bar app into ~/Applications when a release exists. It
prints every step before doing it and never runs sudo itself; only
Homebrew’s own installer, if you accept it, asks for your password. At
the end it offers benchbar adopt for a bench it finds, or benchbar install; you can say no and run them yourself as below. The last line
is BenchBar is installed., and benchbar --version in a new Terminal
tab prints the version.
With Homebrew, brew install askysh/tap/benchbar askysh/tap/benchbar-app
does the same; see Install. Either way, the app
carries its own copy of the CLI and every benchbar hands off to it.
Two words you will see a lot: a bench is the folder that holds a
Frappe installation (its apps, its Python environment and its sites),
and a site is one Frappe instance inside it, with its own database
and its own address such as http://macdev:8000.
Then pick one:
-
You already have a bench: run doctor on it. The examples on this page use
~/frappe-bench; put your bench’s folder in its place.benchbar doctor --bench-dir ~/frappe-benchIt is read only and prints
[OK],[WARN]or[FAIL]per check, with the exact fix under every WARN and FAIL. If it looks right, register the bench so the app and thebench*helpers see it:benchbar adopt ~/frappe-benchadoptshows its plan and asks before writingProcfile.lean(the list of processes the bench runs), the runner script and the launchd agent (the macOS service that keeps the bench running in the background). It never runsmigrate,buildorupdate, and never touches your apps, sites or databases. The one exception: when the bench uses the same ports as another bench benchbar knows, the plan says so and, after asking, writes new port numbers intosites/common_site_config.json(with a backup first). -
You have no bench yet: run
benchbar install. It asks for the folder (default~/frappe-bench), the site name (defaultmacdev) and the site’s Administrator password, generates a MariaDB root password and keeps it in your Keychain (the macOS password store), and does the rest, including the MariaDB setup and the patched wkhtmltopdf. It asks for yoursudopassword once, for the wkhtmltopdf package and the/etc/hostsline. It ends with a list of steps markeddone; re-running it is always safe, and a second run saysunchanged.
Open a new Terminal tab afterwards, or run source ~/.zshrc.
2. Try it
benchup # start the bench in the backgroundbenchstatus # state, pid, site pingopen http://macdev:8000benchlogs # follow the log (Ctrl+C to stop following)benchdown # stop it, also across rebootsbenchup ends with bench is up: http://macdev:8000, and benchstatus
shows web ping 200 while the site answers. If you picked another site
name, use it in place of macdev; benchstatus shows the address.
Things worth checking:
-
Close Terminal after
benchup. The site should keep answering. -
Open the BenchBar app from
~/Applications. The runner in the menu bar sleeps when the bench is stopped and runs when it is up. Click it for Start, Stop, Restart, the site, logs and a read only doctor. -
Break something on purpose, safely: stop the bench first, since its processes run from the Python environment in
env/, then move that folder aside (moved, not deleted) and run doctor:benchdownmv ~/frappe-bench/env ~/frappe-bench/env.awaybenchbar doctorDoctor should report the missing env as a
[FAIL]and namebenchbar repairas the fix. Undo it by moving the folder back,mv ~/frappe-bench/env.away ~/frappe-bench/env, thenbenchup. Or letbenchbar repairbuild a new env, which takes a few minutes; thenenv.awayis left over and you can delete it once the bench runs. -
Reboot. If the bench was running it comes back on its own; if you had run
benchdownit stays down.
Everything is idempotent: run benchbar install, repair or adopt
twice and the second run says unchanged.
More to try
- The BenchBar window: ⌘M in the popover (or open BenchBar again from Spotlight). Each bench has Overview, Sites, Apps and Health. Right click a bench in the sidebar for its actions.
- A new bench from the app: in the sidebar footer, Add Bench,
then New Bench…. The wizard checks your Mac, shows the plan from
benchbar install --dry-run, and streams each step. macOS asks for your password in its own dialog for two steps. Settings (⌘,) and About BenchBar are the other two buttons of the footer. - Windows: install as in Windows, then open
the tray flyout and try Start, Stop and Doctor. A test build comes
with its own
install.ps1: see A test build you were sent. - Add an app: Apps, then Add App…. Pick one from the list or
paste a GitHub URL; a private repo works when
git cloneof it works in your Terminal (SSH key orgh auth login). It shows the plan, then clones, installs on the site you picked and builds. - Update an app: Update… on an app shows the commits it would take before anything changes, then backs up every site that has the app, fast forwards, migrates and builds.
- Repair from the app: Health, then Repair…. It lists what it would do before it does it.
- The log window: ⌘L, with search (⌘G for the next match) and a filter per process.
- A second bench:
benchbar install --profile v16-lts --bench-dir ~/v16-benchputs a Frappe v16 bench in a new folder next to your first one, on its own ports; both show up in the menu bar. It asks for the new site’s name and Administrator password, like the first install. - Your team’s profile:
benchbar profile create myteam --from-bench ~/frappe-benchwrites~/.config/benchbar/profiles/myteam.tomlfrom a bench you already have (it only reads the bench). A teammate with that file runsbenchbar install --profile myteam. - A coding agent:
claude mcp add benchbar -- benchbar mcp, then ask it how your benches are doing. In Terminal,benchbar status --for-agentandbenchbar commands --jsonshow what an agent reads.
Coming from an older version: update as in
Updating, then run benchbar doctor. If it says
the runner script is outdated, benchbar repair rewrites it (it asks
first).
3. Send a report
Whether it worked or not, run:
benchbar reportIt writes ~/Desktop/benchbar-report-<date>.zip with the doctor and
status output, the versions of macOS, Homebrew, Python, Node, MariaDB,
Redis, bench, Frappe, ERPNext and BenchBar, the launchd agent, and the
last 200 lines of the bench and worker logs.
The zip is safe to share: site config files are reduced to their key
names, every value whose key looks like a password, secret, token, key or
API credential is replaced by ***, and your home folder, username and
hostname are replaced by placeholders. REDACTIONS.txt inside the zip
lists what was replaced. benchbar report --print shows the same content
in the terminal if you want to look first.
Attach the zip to a new issue at https://github.com/askysh/benchbar/issues with one or two lines on what you did and what you expected. Screenshots of the app are welcome.
Uninstall
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/main/install.sh | bash -s -- --uninstallremoves the app, the benchbar links and the PATH block. Then it asks,
one at a time, whether to stop each bench’s launchd agent and remove it
with its runner and Procfile.lean, and whether to delete the checkout
in ~/.local/share/benchbar. The logs and file backups of every
benchbar run stay in ~/.local/state/benchbar; move that folder to the
Trash yourself when you no longer want them. Your benches, their sites
and databases, the Homebrew packages and the MariaDB password in the
Keychain stay. Add --dry-run after --uninstall to see the list
first. benchbar uninstall-service alone removes only the background
service of one bench. For a Homebrew install, see
Uninstall.
Running the test suite (contributors)
tests/affected.sh # only the tests your change touches (from origin/main; --base REF, --all)tests/run-tests.sh # every test, as many at a time as you have CPUsPARALLEL=1 tests/run-tests.sh # one after anothertests/run-tests.sh test-doctor # only the named testsSHARD=2/4 tests/run-tests.sh # the second of four shards, as CI runs themLIST_ONLY=1 SHARD=2/4 tests/run-tests.sh # which tests that shard holds, without running themtests/affected.sh maps the changed files to tests: a file in
lib/frappe-local/ picks its own test files, every test that names a
function it changed, test-cli and test-agent-contracts; a change to
the harness, the mocks, benchbar, templates/ or the phase scripts
runs everything, and docs alone run nothing. Run the whole suite before
you hand work back.
Each test’s output is printed whole when it finishes, in list order, and
a failing test does not stop the others: the run lists every failure at
the end and exits 1. TEST_TIMEOUT (default 600 seconds) kills a hung
test and prints its process tree. A new tests/test-*.sh must be added
to the list in tests/run-tests.sh, or the run fails; give it a time in
TEST_SECS there too, since shards are filled heaviest first from those
times (a test without one counts as 10 seconds).
The app and its Swift tests build with scripts/macos-build.sh --test.
Issues and pull requests are welcome. For a bug, attach the zip from
benchbar report; it contains no secrets, paths or names. Shell code
targets macOS /bin/bash 3.2 with no dependencies beyond the ones the
installer needs, passes shellcheck, and every command stays idempotent:
a second run changes nothing and says so. CI runs the suite in 8 Linux
shards, 4 shards under bash 3.2.57 in a container (the bash of macOS) and
4 macOS shards, builds the app, and uploads an unsigned bundle for every
pull request.