Skip to content

Configuration

benchbar has no settings file of its own to edit. A bench is configured by the flags you pass once (they are remembered per bench), the profile and bundle it was installed with, and a few environment variables.

Profiles

Profiles pick the Frappe branch and the matching toolchain:

ProfileFrappeERPNextPythonNodeMariaDB
v15-lts (default)version-15version-15python@3.11node@22mariadb@10.11
v16-ltsversion-16version-16python@3.14node@24mariadb@11.8

Every profile also installs pkgconf (pkg-config) and mariadb-connector-c, which mysqlclient needs to build on v16. When uv is on PATH, bench itself is installed with uv tool install frappe-bench, as the Frappe docs now recommend; an existing pipx install is kept, and doctor says which one owns bench.

Each profile accepts a range of MariaDB servers: 10.6 to 10.11 for v15-lts, 10.6 to 11.8 for v16-lts. A v16 bench shares the mariadb@10.11 server a v15 bench runs, so one MariaDB serves every bench. The profiles are defined in config/release-profiles.tsv.

--profile NAME picks one for install; a bench remembers its profile. A name that is not built in is looked up as a team profile.

App bundles

App bundles pick what install adds beyond Frappe: minimal (erpnext), common (erpnext hrms payments), extended (erpnext hrms payments crm helpdesk insights). Definitions live in config/: config/app-bundles.tsv for the bundles, config/apps.tsv for the app registry that benchbar app add NAME reads, with the branch each app follows per profile.

benchbar install --profile v16-lts --bundle common
MARIADB_ROOT_PASSWORD='...' ADMIN_PASSWORD='...' benchbar install --yes # non interactive
benchbar autostart off # never start at login

--yes accepts every default and confirmation, including the sudo line for /etc/hosts; the sudo password prompt itself still appears. ADMIN_PASSWORD must be in the environment. MARIADB_ROOT_PASSWORD is needed only when MariaDB already has a root password that the Keychain does not know: a fresh MariaDB gets a generated one.

Team profile files

A team profile is NAME.toml in ~/.config/benchbar/profiles/ (your own files and the ones profile import wrote), then in each subscription (~/.config/benchbar/sources/, in the order of ~/.config/benchbar/sources.list), then in each folder of BENCHBAR_PROFILE_PATH. The first file of a name wins, and a built in profile of the same name wins over all of them. The format is a strict subset of TOML: strings, booleans, integers and one line lists; no escapes, no inline tables.

KeyRequiredWhat it sets
schemano1 or 2; 1 when absent. A file with any schema 2 key must say schema = 2
baseyesThe built in profile for Python, Node and MariaDB, for example "v15-lts"
descriptionnoOne line shown by profile list
frappe_branchnoAnother Frappe branch than the base’s
frappe_commitnoA commit to pin frappe to (7 to 40 lower case hex characters). install checks that the clone has it before it builds, and stops otherwise
erpnext_commitnoThe same for erpnext (also [[apps]] commit for an erpnext listed there)
bundlenoAn app bundle, instead of [[apps]]: a file with both is refused
sitenoThe default site name for install
schedulernotrue to run the scheduler
sourceno, schema 2Where profile import fetched the file (an https URL or a path); profile update fetches it again
exported_fromno, schema 2Written by profile export, for example "benchbar 0.6.0, 2026-09-29"
[[apps]] nameyes, per appThe app’s folder name
[[apps]] repoyes, per appIts git URL. A URL with a user name or token is refused
[[apps]] branchyes, per appThe branch to clone
[[apps]] commitnoA commit to pin; a clone that does not reach it stops install before anything is built
[[apps]] accessno, schema 2public, private, personal or unknown: who can read the repo, as profile export found it
[[apps]] requiresno, schema 2The apps this one needs, for example ["acme_base"]. install --profile leaves an app out when one it requires cannot be read

A benchbar before 0.6 refuses a schema 2 file with “not supported: schema 2”, so update benchbar before you share one. An example is in Teams. benchbar profile create writes one from a bench you have, benchbar profile export a copy to share (Sharing a profile).

Passwords

WhatWhere it livesWhen you need it
MariaDB rootyour Keychain, item benchbar-mariadb (on Linux a 0600 file in the state folder); benchbar mariadb-password prints it after a confirmationrarely: another bench new-site, or mariadb -u root -p
Administratoryou choose it during benchbar install or site add, or ADMIN_PASSWORDevery login at http://<site>:<port>, by default http://macdev:8000

Environment variables

VariableUsed byWhat it does
MARIADB_ROOT_PASSWORDinstall, site add, pullThe MariaDB root password. A fresh MariaDB gets a generated one when unset; an existing one is read from the Keychain
ADMIN_PASSWORDinstall, site add, pullThe Administrator password of a new site; for pull, a new Administrator password for the copy
BENCHBAR_PROFILE_PATH--profile, profileColon separated folders with team profiles, for example a clone of your team’s config repo
BENCHBAR_OFFLINEinstall, profile, doctorBENCHBAR_OFFLINE=1: no network for team profiles, and no remote branch checks in install; reachability is null and doctor does not fetch subscriptions
BENCHBAR_LOCKlock, doctorThe lockfile path, when --lock is not given
BENCH_DIRevery commandThe bench to act on when --bench-dir is not given; checked before the remembered bench
SITE_NAMEevery commandThe site to act on when --site is not given; checked before the remembered site
OFFLINEinstall, doctor, app focus, profileOFFLINE=1: no network for version checks, --fetch and team profiles (like BENCHBAR_OFFLINE=1)
BENCHBAR_REPORT_DIRreportWhere the zip goes instead of ~/Desktop
NO_COLORevery commandNO_COLOR=1 turns off colors and spinners, like --plain
BENCHBAR_NO_HANDOFFevery commandBENCHBAR_NO_HANDOFF=1: Homebrew’s or the one line installer’s benchbar runs itself instead of handing off to the CLI inside BenchBar.app (0.7.1)
BENCHBAR_NONINTERACTIVEevery commandBENCHBAR_NONINTERACTIVE=1: nothing is asked. A command that lacks an input names all of them in one error before it takes the lock. --for-agent and benchbar mcp set it
BENCHBAR_SUDOinstall, adopt, repair, ports apply, site hostsBENCHBAR_SUDO=gui (macOS): each root step asks in macOS’s own password dialog, at most two per run. The BenchBar app sets it

The one line installer reads BENCHBAR_HOME (the checkout, default ~/.local/share/benchbar), BENCHBAR_BIN_DIR (default ~/.local/bin), BENCHBAR_APP_DIR (default ~/Applications) and BENCHBAR_RC_FILE (default ~/.zshrc). The CLI writes its helper block to $ZDOTDIR/.zshrc when ZDOTDIR is set, and remembers that file, so a run started by the app or launchd (without the terminal’s variables) finds the same block.

Bench discovery

Point the tool at any bench once with --bench-dir; the path is remembered. Without it, benchbar uses BENCH_DIR when it is set, then the remembered bench, then ~/frappe-bench, ~/dev/frappe-bench, and any folder directly under ~ or ~/dev (one level deep) that holds sites/common_site_config.json. benchbar scan PATH looks deeper.

The first bench you install or adopt becomes the default; a second one keeps the first as the default unless you pass --make-default. See Several benches.

Port blocks

Each bench uses a block of four ports: web 8000 + n, socketio 9000 + n, Redis 11000 + n and 13000 + n. --port-offset N picks block N for install, adopt or service. How a clashing bench is moved is in Port blocks.

Where state lives

  • benchbar’s state folder is ~/.local/state/benchbar for Homebrew, the one line installer and the CLI inside BenchBar.app, and .benchbar next to the CLI in a git checkout. benchbar where shows it.
  • Per bench settings (profile, site, scheduler, autostart, lockfile path) live in its benches/ folder, one file per bench.
  • The logs and backups of every mutating run are in the same folder: logs/<timestamp>.log and backups/<timestamp>/.
  • The runner writes <bench>/logs/.benchbar/state.json on every state change (schema).
  • Everything else benchbar writes is listed in Troubleshooting.