Skip to content

install and adopt

These commands set a bench up. install builds a new one from nothing, adopt registers one you already have, and service refreshes only the background service. All three are safe to run again: a second run says unchanged.

Options for every command

These come from benchbar --help and work with every command below.

FlagWhat it does
--bench-dir DIRBench to act on (default: remembered, or auto detected)
--site NAMESite name (default: remembered, or from the bench)
--dry-runPrint the full plan, change nothing
-y, --yesDo not ask; secrets must come from the environment
--jsonVersioned JSON: one document for a command that reads, JSON lines for one that changes things (JSON schema)
--jsonlJSON lines (plan, step, progress, done) for any command that changes things
--for-agent--jsonl for a command that changes things, --json for one that reads, plus BENCHBAR_NONINTERACTIVE=1, NO_COLOR=1 and --plain
--plainNo colors or spinners (also: NO_COLOR=1, or a non TTY)
-h, --helpThe help. benchbar COMMAND --help prints that command’s flags, what it needs (a terminal, sudo, the network) and whether it changes things
--versionPrint the version, and the BenchBar app’s when it is installed

The environment variable BENCHBAR_NONINTERACTIVE=1 makes a command refuse to ask. One that needs an input it does not have names all of them in one error, before it takes the lock or touches a bench. See Coding agents and MCP.

benchbar commands --json lists every command with its flags, its environment variables and what each needs, as one document.

install

benchbar install [--profile NAME] [--bundle NAME] [--make-default] [--port-offset N] [--frappe-commit SHA] [--erpnext-commit SHA] [--offline] [--dry-run] [--yes] [--json]

Runs phase 00 (system dependencies), phase 01 (bench and site) and the background service, with a live step list. Safe to re-run: it only changes what changed.

It asks for two passwords, the MariaDB root password (generated unless you set MARIADB_ROOT_PASSWORD, kept in your Keychain) and the site’s Administrator password (or ADMIN_PASSWORD). It asks for sudo once, up front, only when a step ahead needs it: the wkhtmltopdf package and the /etc/hosts line. Those two steps run first, and the sudo credential is dropped (sudo -k) before Homebrew, pip, npm, yarn or bench get-app run anything, so no package’s install script finds a cached sudo. The package is copied into a folder only root can write, hashed there and installed from there. The two passwords stay inside benchbar and the phase scripts: no other program started by the install sees them.

FlagWhat it does
--profile NAMERelease profile (default v15-lts), or a team profile (Configuration)
--bundle NAMEApp bundle: minimal, common or extended
--make-defaultMake this the default bench even when another one is already the default
--port-offset NUse port block N (web 8000+N, socketio 9000+N, redis 11000+N and 13000+N). Default: keep the ports, or the next free block when another bench already uses them
--with-schedule, --without-scheduleAdd the scheduler to Procfile.lean, or leave it out (the default)
--dry-runPrint the plan of every phase, change nothing
--frappe-commit SHA, --erpnext-commit SHAPin frappe or erpnext to a commit (7 to 40 hex characters; a team profile can say frappe_commit and erpnext_commit). The flag wins over the profile. A pinned clone is fetched without its first build, the commit is checked out, and one build follows. A commit the clone does not reach stops the install before anything is built or created
--offlineSkip the remote branch checks of both phase scripts (also OFFLINE=1 or BENCHBAR_OFFLINE=1)
--allow-windows-fsWSL only: accept a bench on the Windows file system (/mnt/c, drvfs, 9p). Refused by default: it is very slow, file watching does not work and permissions break
-y, --yesAccept every default and confirmation, including the sudo line for /etc/hosts; the passwords must be in the environment
--jsonJSON lines for the BenchBar app and agents: plan, step, progress and a closing done (schema). Needs --yes or --dry-run, takes every value from a flag or the environment and never asks

BENCH_INIT_TIMEOUT_SECONDS sets how long bench init may run before it is stopped (default 2700, 0 for no limit). A half built bench left by a stopped init, with frappe as its only app and no site, is moved aside (never deleted) by the next install, which starts bench init again. A bench with another app or a site is never moved: install stops and names benchbar repair.

With --yes the confirmation is skipped but the sudo password prompt is not. When the BenchBar app runs it, BENCHBAR_SUDO=gui is set, and each of the two steps that need root asks in macOS’s own password dialog, at most two per run (the privileged steps).

Exit codes: 0 success; 1 a step failed; 2 phase 00 or 01 stopped for a manual step, most often a MariaDB root password that neither the environment nor the Keychain knows (pass MARIADB_ROOT_PASSWORD). System dependencies may be set up; no bench or site was created.

MARIADB_ROOT_PASSWORD='...' ADMIN_PASSWORD='...' benchbar install --profile v16-lts --bundle common --yes

adopt

benchbar adopt PATH [--make-default] [--port-offset N] [--site NAME] [--dry-run] [--yes] [--json]

Registers an existing bench: Procfile.lean, the runner, the agent, the shell helpers and the hosts line. It shows the plan and asks; it never runs migrate, build or update, and never touches apps/, env/, the sites or the databases.

When the bench uses the same ports as an established bench, adopt moves it to the next free port block, after asking: bench set-config -g writes the port keys into sites/common_site_config.json (backed up first) and bench setup redis rewrites config/redis_*.conf. That is the only change under sites/. The default bench never moves on its own. When honcho is missing, adopt warns and does not install it into the bench env.

FlagWhat it does
--make-defaultMake this the default bench even when another one is the default
--port-offset NUse port block N instead of the automatic choice
--site NAMEThe site benchup waits for, when the bench has several
--allow-windows-fsWSL only: accept a bench on the Windows file system (/mnt/c, drvfs, 9p), which is refused by default
--dry-runPrint the plan, change nothing
-y, --yesApply without asking
--jsonJSON lines, as for install (schema); needs --yes or --dry-run

A bench path with a double quote, backslash, $, backtick, <, >, & or a control character in it is refused before anything is written: the runner script and the launchd agent cannot carry it as plain text. Move the bench to a plainer folder (spaces and apostrophes are fine).

Exit codes: 0 adopted (or unchanged); 1 the path is not a bench, the path has a character the service files cannot carry, the plan was cancelled, or a step failed.

benchbar adopt ~/frappe-bench

service

benchbar service [--with-schedule | --without-schedule] [--port-offset N] [--make-default] [--json] [--bench-dir DIR]

Installs or refreshes only the background service (phase 02): the lean Procfile, the runner, the launchd agent and the shell helpers.

FlagWhat it does
--with-scheduleAdd the scheduler to Procfile.lean (per bench, kept by repair)
--without-scheduleRemove it again (the default)
--port-offset NMove the bench to port block N
--make-defaultMake this the default bench
--dry-runPrint the plan, change nothing
--jsonJSON lines ending in a done (the done fields)

After a scheduler change on a running bench, run benchbar restart.

Exit codes: 0 success; 1 failure.

benchbar service --port-offset 1 --bench-dir ~/dev/v16-bench

The phase scripts

The three phases also run on their own from the checkout: 00-mac-system-deps.sh, 01-install-bench-and-site.sh and 02-background-service.sh. See Troubleshooting for their flags.