Skip to content

benchbar JSON API, schema version 1

benchbar (and its alias frappe-mac) prints versioned JSON for the commands below, and the runner writes one state file per bench. The BenchBar app reads nothing else, so this is a public API: coding agents, scripts, Raycast extensions and the like can rely on it too.

SourceWhat it is
benchbar list --jsonevery bench benchbar knows about
benchbar status --json [--bench-dir DIR]the live state of one bench
benchbar doctor --json [--bench-dir DIR]every health check with its fix
benchbar app list --jsonthe bench’s apps, their git state and sites (0.5)
benchbar app update NAME --dry-run --jsonthe changelog and plan of an update (0.5)
benchbar app focus --jsonfocus apps and how far behind the apps they need are (0.6), see app focus
benchbar profile list --jsonbuilt in and team profiles, with where each comes from (0.5)
benchbar profile export|import|subscribe|update|remove|check ... --jsonsharing team profiles (0.6), see profile sharing
benchbar lock check --jsonhow the bench differs from its benchbar.toml (0.5)
<bench>/logs/.benchbar/state.jsonthe last state transition, written by the runner and the CLI
<bench>/logs/.benchbar/heartbeatsince 0.6.1: rewritten in place every 30 seconds while the runner runs; its mtime says the runner is alive
benchbar pull ... --jsonJSON lines while a production site is copied, see pull
benchbar install --json, benchbar adopt PATH --jsonJSON lines while a bench is created or adopted (0.8), see install
benchbar doctor --prerequisites --jsonwhat the Mac needs before an install, without a bench (0.8), see prerequisites
benchbar report --jsonwhere the redacted diagnostics zip went (0.5.5), see report
benchbar commands --jsonevery command, flag and what it needs (0.8), see the done fields
benchbar where --jsonhow this CLI was installed, the path it records for itself, its state folder and the app (0.7), see where
benchbar site backup NAME --jsonthe backup just taken (0.5.8), see site backups
benchbar site backups NAME --jsonevery backup of a site (0.5.8)
benchbar up|down|restart|service|site add|site default --jsonJSON lines ending in one done (0.8), see the done fields
benchbar site drop NAME --jsonthe plan (with --dry-run) or the result of dropping a site (0.5.8)

Rules for readers

  • Every document has "schema_version": 1 and "cli_version" at the top. The schema version goes up only for a change that breaks readers: removing or renaming a field, or changing its type or meaning.
  • Adding fields is not a breaking change. Ignore fields you do not know.
  • Treat an enum value you do not know (a new state or stop_reason) as “unknown”, never as an error.
  • Timestamps are ISO 8601 in UTC with a Z suffix, for example 2026-09-23T10:00:00Z.
  • null means “not known” or “does not apply”. Numbers are JSON numbers.
  • JSON goes to stdout on one line. Errors and warnings go to stderr as text. Exit codes: 0 success, 1 failure (for doctor: at least one check is fail; the JSON is still printed). A missing bench exits 1 with a message on stderr and nothing on stdout.
  • status --json, list --json and doctor --json are read only. They never start, stop or write anything, so they are safe to poll. The one exception is the one time move of the state folder on the first run after an upgrade (state.sh), which renames and links, and never copies or deletes.

The done fields (0.8)

Every command that changes things ends with the same fields, once: in the done line of its stream, or added to the one document it prints. A command that read only prints none of them.

fieldmeaning
exitthe exit code; the process exits with the same number, so a pipe cannot hide a failure
changed[]what the run changed: {"kind": "bench"|"site"|"app"|"service"|"ports"|"hosts"|"backup"|"process"|"state", "name", "detail"}. Only what the run really changed: empty on a second run, and in a dry run. install reports the bench, the site and the apps its phase scripts create
warnings[]the run’s [WARN] lines, as text
next_actions[]{"command", "why"}: the fix lines and next steps the text output prints
state_afterthe bench’s status --json object after the run (no per site ping), null when there is no bench, in a dry run, or when the run touched several benches (ports apply). A stream’s is read after the CLI’s locks are released; a one document command’s and pull’s while its lock is still held (a read, so nothing waits on it)
missing[]only on a refusal of the non interactive mode: the inputs the command lacked (ADMIN_PASSWORD, --yes, sudo, BENCHBAR_SUDO_PASSWORD, …)
error_idonly on a failure that has a stable id, for programs to match instead of the text. Every CLI done line can carry it. So far: sudo_password_wrong (the password in BENCHBAR_SUDO_PASSWORD was refused, before any change). password_has_newline (a password in ADMIN_PASSWORD, MARIADB_ROOT_PASSWORD or BENCHBAR_SUDO_PASSWORD holds a line break; it travels on one line; refused before any change, only the variable’s name is printed). systemd_not_running (Linux, install only: PID 1 is not systemd, and MariaDB, Redis and the bench service are systemd services; on WSL the fix names [boot] systemd=true in /etc/wsl.conf), bench_on_windows_fs (WSL, install and adopt: the bench folder is on the Windows file system, /mnt/<drive> or a drvfs or 9p mount; slow, no file watching, broken permissions; --allow-windows-fs accepts it), github_unreachable (Linux, install only: github.com, which holds frappe and the uv Pythons, did not answer within 10 seconds, after one retry; the plan’s blockers[] names it, nothing was changed) and port_3306_in_use and port_6379_in_use (Linux, install only: another program, or on WSL another distro, already listens on the MariaDB or the system Redis port; the plan’s blockers[] names them, the done line has exit 1, the fix and the error, and nothing was changed, no sudo asked). Docker, a native MariaDB or a second WSL distro are the usual cause: WSL distros share one network, so only one of them can run MariaDB on port 3306. Stop it in the other distro (sudo systemctl stop mariadb) and run install again; benchbar never stops it. The Windows shim adds distro_running, see Windows shim

Which shape a command prints:

  • A command that printed one document before keeps printing exactly that one line with --json. The ones that change things (site backup, site drop, app add --apply, doctor --ack and --unack) get the done fields added to it; a plan or dry run document gets none; the ones that only read (site backups, ports plan, the profile commands) have none of them. A run that fails prints nothing on stdout and a message on stderr, except the refusal of the non interactive mode, which is one document with exit, error and missing.
  • --jsonl asks any command that changes things for the stream (plan, step, progress, done): the done line carries the same fields and the fields of the document the command would have printed (site backup, site drop, app add, app update). On a command that only reads, --jsonl is --json.
  • up, down, restart, service, site add, site default, app update (without --dry-run) and ports apply had no JSON before and stream with plain --json, as install, adopt, repair and pull do. A dry run streams the plan line and the done line only.
  • --for-agent is --jsonl for a command that changes things, --json for one that reads, plus BENCHBAR_NONINTERACTIVE=1, NO_COLOR=1 and --plain.
  • stdout carries JSON and nothing else under --json and --jsonl: the [OK], [WARN] and [FAIL] lines and the step lines go to the run’s log and stderr, a refusal included.
  • repair --json keeps exit_code in its done and adds exit with the same value. install, adopt and pull add the fields to their done.
  • BENCHBAR_NONINTERACTIVE=1 (set by benchbar mcp for every CLI it starts): nothing is ever asked. A command that needs an input it does not have (ADMIN_PASSWORD, MARIADB_ROOT_PASSWORD when benchbar has none stored, --yes for a confirmation, a sudo that would ask) names all of them in one error and exit 1 (exit 2 when the MariaDB root password is one of them), before it takes the lock, writes a log or touches a bench. In a stream that is a done with exit, an error and missing; under --json on a one document command, one document with the same fields. repair --json also ends with a done when it stops early (no bench).
  • benchbar commands --json lists every command and subcommand with its flags, environment variables and what it needs (tty, sudo, network, mutating, json: document, stream or none); benchbar COMMAND --help prints that entry.

States

stateMeaningstop_reason
stoppednot runningmanual after benchdown, null otherwise (never started, logout or restart in progress)
startingprocesses are up, the site does not answer yetnull
runningprocesses are up and the site answers HTTPnull
crashedhoncho exited with an error; launchd retries after 20 secondscrash
not_adopted(0.8) a folder that is a bench, with no benchbar service and not remembered (not the default bench, no state of its own, not registered), and nothing running. site and web_url are null: the site of the default bench is never named for it. benchbar adopt PATH or register changes itnull
pausedauto-restart is off until benchupcrash (the crash guard tripped: 3 starts in 10 minutes), broken (honcho or the env is missing, or the runner cannot write the crash history or the stop flag: run benchbar repair or benchbar doctor) or port_conflict (another process held the bench’s ports when the runner started; it was not this bench’s to stop: run benchbar doctor)

stop_reason can be manual, crash, broken, port_conflict or null. broken and port_conflict are additions to the original manual | crash | null contract: they tell a reader that repair or doctor is needed, not just benchup.

How status decides (live facts win over the state file):

  1. Processes of this bench are running: running when the site answers any HTTP code, otherwise starting. A bench started by hand with benchfg counts as running. While the runner’s state.json says running or starting and launchd runs that very pid, that is the answer; otherwise one process scan looks for this bench’s honcho, serve, worker, schedule and socketio (0.6.1: port listeners alone no longer count, a leftover Redis is not a running bench).
  2. The stop flag logs/.bench-stopped says manual: stopped.
  3. It says crash: paused with crash. port_conflict: paused with port_conflict. Anything else: paused with broken.
  4. state.json says crashed: crashed (launchd is about to retry).
  5. Otherwise stopped with stop_reason: null.

benchbar list --json

{
"schema_version": 1,
"cli_version": "0.3.0",
"default_bench": "/Users/you/frappe-bench",
"benches": [
{
"path": "/Users/you/frappe-bench",
"name": "frappe-bench",
"site": "macdev",
"label": "com.benchbar.frappe-bench",
"web_url": "http://macdev:8000",
"ports": { "web": 8000, "socketio": 9000, "redis_queue": 11000, "redis_socketio": 13000, "redis_cache": 13000 },
"default": true,
"service_installed": true,
"state_file": "/Users/you/frappe-bench/logs/.benchbar/state.json"
}
]
}
FieldTypeNotes
default_benchstring or nullthe bench commands use without --bench-dir
benches[].pathstringabsolute path, the unique key of a bench
benches[].namestringfolder name, used in the agent label
benches[].sitestringdefault site
benches[].labelstringlaunchd label, com.benchbar.<name>
benches[].web_urlstringhttp://<site>:<web port>
benches[].portsobjectweb, socketio, redis_queue, redis_socketio, redis_cache. redis_socketio was added in 0.4: bench keeps it equal to redis_cache and frappe v15 and v16 never connect to it; older CLIs leave it out
benches[].sitesarrayadded in 0.4, see Sites
benches[].defaultboolsame as path == default_bench
benches[].service_installedboolthe agent plist exists
benches[].state_filestringwhere the runner writes state.json

Benches are found in this order, without duplicates: the remembered bench (state.env in benchbar’s state folder), the WorkingDirectory of every com.benchbar.* and com.frappe-mac.* agent, then ~/frappe-bench, ~/dev/frappe-bench and any ~/* or ~/dev/* folder with sites/common_site_config.json.

list --json never pings a site (every ping_code is null) and looks for no listener: it is polled at rest (0.6.1).

benchbar status --json

{
"schema_version": 1,
"cli_version": "0.3.0",
"bench": "/Users/you/frappe-bench",
"name": "frappe-bench",
"site": "macdev",
"label": "com.benchbar.frappe-bench",
"state": "running",
"stop_reason": null,
"pid": 4242,
"started_at": "2026-09-23T10:00:00Z",
"last_exit_code": 0,
"web_url": "http://macdev:8000",
"web_ping_code": 200,
"ports": { "web": 8000, "socketio": 9000, "redis_queue": 11000, "redis_socketio": 13000, "redis_cache": 13000 },
"state_file": "/Users/you/frappe-bench/logs/.benchbar/state.json",
"log": "/Users/you/frappe-bench/logs/bench.log",
"agent_loaded": true,
"agent_state": "running",
"processes_running": true,
"url": "http://macdev:8000",
"agent": "com.benchbar.frappe-bench",
"loaded": "yes",
"stop_flag": "none",
"ping": "200"
}
FieldTypeNotes
benchstringabsolute path of the bench
name, site, labelstringas in list
statestringsee States
stop_reasonstring or nullsee States
pidnumber or nullthe runner process launchd started; honcho and every bench process are its descendants. Set while starting or running
started_atstring or nullwhen the current (or last) run started
last_exit_codenumber or nullexit code of the last run of honcho
web_urlstring
web_ping_codenumber or nullHTTP code of GET /api/method/ping with the site as Host; null when nothing answered. Asked only while processes run, with a 2 second limit (3 seconds before 0.6.1)
portsobjectas in list
state_file, logstringpaths
agent_loadedboolthe launchd agent is loaded
agent_statestring or nulllaunchd’s own word, for example running or not running
processes_runningboolany honcho, serve, worker, schedule or socketio process of this bench (before 0.6.1 a port listener counted too)
sitesarrayadded in 0.4, see Sites
schedulerbooladded in 0.4: Procfile.lean runs bench schedule (benchbar service --with-schedule)
redisobjectadded in 0.8: {"queue": {"port", "running"}, "cache": {"port", "running"}}. running is whether something accepts a connection on the port, read by bash itself (/dev/tcp), so status starts no new program for it (a subshell for the probe). benchbar up --services-only starts these two and nothing else, benchbar down stops them
pending_operationsarray[] when none. An app update or planned app add that stopped part way, one entry per app: op (app_update or app_add), app, branch, from, to (commits; from is null for an add), steps[] (kind, target, name of the steps not done yet), failed_step (the kind it stopped at, or null), reason (that step’s own failure line, or null) and updated_at. Read from a record file in the bench’s state folder: no extra process on the status path

Kept from frappe-mac 0.2.0 for older readers: url, agent, loaded ("yes" or "no"), stop_flag ("manual", "crash", "broken", "port_conflict" or "none"), ping (string, "000" for no answer). In 0.2.0 state held launchd’s word (now agent_state), and pid and last_exit_code were strings.

Since 0.8, bench_bin is the bench executable the bench’s service runs: the first one on the PATH its agent (unit) bakes in, null without a service or when no such file is there. It is read from the agent file in bash, so status still starts no process for it. With --ping, every site is asked only while the bench’s processes run; a stopped bench is never pinged and never started.

Sites

list --json (per bench), status --json and benchbar site list --json carry the bench’s sites, read from sites/*/site_config.json:

"sites": [
{ "name": "v16dev", "default": true, "hosts_entry": true, "ping_code": 200, "developer_mode": true, "open_as_enabled": true, "open_as": true },
{ "name": "v16two", "default": false, "hosts_entry": false, "ping_code": null, "developer_mode": false, "open_as_enabled": false, "open_as": false }
]
FieldTypeNotes
namestringthe site folder
defaultboolthe site benchup waits for, the runner pings and the app opens; benchbar site default NAME changes it (and runs bench use)
hosts_entrybool/etc/hosts maps it to 127.0.0.1; benchbar site hosts adds the missing lines
ping_codenumber or nullHTTP code of /api/method/ping with this site as Host; null when nothing listens on the web port or nothing answered. Since 0.6.1 list --json and status --json leave it null (they are polled; web_ping_code is the default site’s ping) unless status --json --ping asks every site once; site list --json always asks
developer_modebooladded after 0.8.0: developer_mode as frappe sees it, the site’s site_config.json over common_site_config.json; 1 or true is on. benchbar open --as signs in as another user only when it is on
open_as_enabledbooladded after 0.8.0: the person turned Open as on for this site (benchbar site open-as on NAME). Benchbar’s own state for the bench; off for every site until then, also for a site added or pulled later
open_asbooladded after 0.8.0: benchbar open --as can sign in on this site: open_as_enabled and developer_mode are on and it is the site the web process answers as (bench serve without --site answers as the default_site of common_site_config.json for every name)
servedbool or nullstatus --json only, added in 0.8: does the running web process serve this site (its Host is not answered with a 404). null while the bench is stopped (a stopped bench is never pinged) or when nothing answered. The default site’s ping, and with --ping every site’s, is reused; any other site is asked once, in bash. false is a site folder in sites/ that the running bench does not serve: doctor’s site_not_served warns about it

benchbar site list --json prints {"schema_version":1,"cli_version":..,"bench":..,"sites":[..]}, and since 0.7.3 each of its sites also carries the database:

FieldTypeNotes
db_namestring or nulldb_name from the site’s site_config.json; null when the file has none
db_portnumberthe site’s db_port, else the bench’s (common_site_config.json), else 3306

The password is never printed. list --json and status --json leave these two out: they are polled.

Since 0.8 every site result carries default_site, the bench’s default site after the run: site list at the top level, and site add, site default and site drop in their result. site add never moves it (it puts it back if bench new-site did); only site default does. site add, site default and site drop end with the done fields, site add and site default with site, default_site and created.

benchbar site add NAME --dry-run --json

The plan of a site add, read only, with the token that --apply TOKEN --yes (and benchbar_site_add over MCP) needs. One document; the text goes to stderr.

{"schema_version":1,"cli_version":"0.8.0","bench":"/Users/you/frappe-bench","site":"qa1.localhost","exists":false,
"apps":["erpnext"],"default_site":"macdev","default_moves":false,"backup":null,"hosts_entry":false,
"steps":[{"kind":"new_site","name":"Create qa1.localhost","command":"bench new-site qa1.localhost ..."},
{"kind":"install","name":"Install erpnext","command":"bench --site qa1.localhost install-app erpnext"}],
"touches":["database","site_folder"],"changes":true,"token":"3f9c0e...64 hex characters"}
FieldTypeNotes
existsboolthe site folder is already there (then no new_site step)
default_sitestringthe default site now (sites/currentsite.txt); default_moves is always false
steps[]arraykind is new_site, install or hosts (macOS, when the line is missing)
touchesarray of stringsdatabase, site_folder, hosts
tokenstringSHA-256 of the plan and of the bench’s site list, apps.txt and default site

--apply TOKEN --yes recomputes the plan and refuses a token that no longer matches before anything changes; then it is a normal site add and its stream ends in the usual done line.

benchbar service --dry-run --json

The plan line of the service stream (as for adopt --json) carries a token: a SHA-256 of the planned actions, the bench, the port block, the scheduler choice and the site. benchbar service --apply TOKEN --yes [--json] runs that plan and refuses, before any action, a token that no longer matches.

MCP results of the site and service tools

benchbar_site_add_plan, benchbar_site_restore_plan and benchbar_service_install_plan return the CLI’s plan (for the service, the plan line of its stream) as structuredContent. The apply tools and benchbar_site_backup return exit_code, output (stderr text), result (the done line, or the one document with the done fields) and the state after: sites (site list --json) for benchbar_site_add and benchbar_site_restore, status for the others. benchbar_site_add adds admin_password and admin_password_generated: true when it generated the new site’s Administrator password. benchbar_up on a bench whose state is not_adopted returns service: "missing", started: false, next_tool: "benchbar_service_install_plan" and the status instead of starting it. Any line of CLI text that would name where the MariaDB root password is kept is replaced by a note in every result and error.

benchbar doctor --json

{
"schema_version": 1,
"cli_version": "0.3.0",
"bench": "/Users/you/frappe-bench",
"name": "frappe-bench",
"site": "macdev",
"profile": "v15-lts",
"profile_source": "stored",
"checks": [
{
"id": "assets",
"group": "bench",
"label": "Built assets",
"level": "fail",
"message": "2 of 2 dist files referenced by assets.json are missing (site loads unstyled)",
"fix_command": "cd /Users/you/frappe-bench && bench build",
"action": "build",
"status": "fail",
"fix": "cd /Users/you/frappe-bench && bench build"
},
{
"id": "agent",
"group": "service",
"label": "launchd agent",
"level": "ok",
"message": "agent com.benchbar.frappe-bench loaded, running (pid 4242)",
"fix_command": null,
"action": null,
"status": "ok",
"fix": ""
}
],
"summary": { "ok": 19, "warn": 1, "fail": 1 }
}
FieldTypeNotes
profile_sourcestringadded in 0.7.3: where profile came from, flag (--profile), team, stored (remembered for the bench), detected (from the bench’s Frappe) or default (no profile matches this bench; the env checks warn instead of offering a rebuild)
checks[].idstringstable id, for example env_python, assets, agent, legacy_agents. 0.7.3 adds env_setuptools (group bench, action env_setuptools), formula_dates (group system, no action) and bench_path (group service, no action). pdf_engine replaced wkhtmltopdf in 0.4. 0.5 adds apps_txt, app_branch_policy, lock_parse and lock_drift (group bench, no repair action). 0.6 adds dependency_behind, apps_behind and profile_outdated (group bench, no repair action); dependency_behind is the one id that can appear several times, once per stale dependency. 0.7 adds app_copies (group system) and cli_duplicate (group service), both without a repair action, and helpers can be fail (the block’s benchbar is gone)
checks[].groupstringsystem, bench, service or site
checks[].labelstringshort name for humans
checks[].levelstringok, warn or fail
checks[].messagestringone line for humans
checks[].fix_commandstring or nullthe exact command a human would run; null when nothing needs doing
checks[].actionstring or nullthe repair action that fixes it, when repair can
summaryobjectcounts per level

status and fix are the 0.2.0 names of level and fix_command (with "" instead of null), kept for older readers.

Since 0.8: every check has "acked", and the document has "acked": [ids], "quick" and "skipped_checks": [ids].

  • doctor --ack CHECK silences one named warn for this bench: it is recorded in the bench’s state file with the message it acknowledged, and lapses when the message changes. A fail cannot be acknowledged. The check stays in the JSON at level warn with "acked": true; the text output prints one dim acked: line instead of the [WARN] and its fix line, and --fix-hints leaves it out. doctor --unack CHECK undoes it. These two write one line to the state file under the CLI lock; doctor itself still writes nothing. Under --json they print one small document: action (ack or unack), check, acked (every id with a stored acknowledgement) and the done fields. An acknowledgement does not make a not_adopted bench look adopted. repair does not look at acknowledgements.
  • doctor --quick leaves out the slow checks (those that start brew, python, node, bench or git, or ask the site) and says which: "quick": true and the ids in skipped_checks.

benchbar logs --json

{"schema_version":1,"cli_version":"0.5.0","bench":"/Users/you/frappe-bench","file":"/Users/you/frappe-bench/logs/bench.log","process":"web","lines":["10:00:01 web.1 | * Running on http://127.0.0.1:8000"]}

-nN sets how many lines (after the filter), --process NAME keeps one honcho process (web, socketio, schedule, redis_queue, redis_cache); lines without a honcho prefix, such as a traceback, stay with the process above them. process is null without a filter. file is the file that was read: logs/bench.log, or logs/worker.log, logs/worker.error.log and logs/bench.previous.log for --worker, --worker-error and --previous. Since 0.7.3 --process worker reads logs/worker.log unfiltered (and process is null): Procfile.lean sends the worker there, so it never appears in bench.log; with --worker-error that file is kept, and --previous is refused (there is no previous worker log). Control characters are removed, a terminal color code as a whole ([31m is never left behind). benchbar mcp uses it for benchbar_logs_tail, whose file argument (bench, worker, worker_error, previous) stands for these flags, and which adds "truncated": true when it had to drop lines to stay under its size cap.

Since 0.7.3 the lines are redacted with the rules of benchbar report (values of credential-like keys, user:password@ in URLs, JWT and API token shapes become ***, email addresses <email>); the plain benchbar logs is the file as it is. -nN is capped at 2000: when N was larger the object carries "truncated_to":2000 (absent otherwise) and holds the newest 2000 lines after the process filter.

Since 0.8 the object also has mtime (the file’s, null without one), since (the cut off as an ISO time, null without one) and ts: one entry per line of lines, in step, an ISO 8601 UTC time where the line carries one and null where it does not (a traceback line inherits nothing). A honcho line’s HH:MM:SS and the leading YYYY-MM-DD HH:MM:SS of other logs are local times; the day of a honcho line is worked out backwards from the file’s mtime. --since TIME keeps the lines at or after TIME (ISO 8601, a zone or none for local time, YYYY-MM-DD HH:MM:SS, a date, or HH:MM:SS today) and the untimed lines under a kept line; --since-restart is --since the bench’s last start (started_at of state.json; without one the command refuses). Only the newest 20000 lines of the file are looked at. benchbar_logs_tail takes since and since_restart.

benchbar repair --json

Since 0.8 its done also carries exit (the same number as exit_code) and the done fields.

A stream: one JSON object per line on stdout, as the run goes. The human text goes to the run’s log, logs/<date>-<time>-<pid>.log in benchbar’s state folder: ~/.local/state/benchbar for the one line installer and Homebrew since 0.7.0, .benchbar/ in a git checkout.

{"event":"plan","schema_version":1,"cli_version":"0.5.0","bench":"/Users/you/frappe-bench","dry_run":false,"actions":[{"id":"build","label":"bench build","fixes":["Built assets"],"sudo":false},{"id":"hosts_entry","label":"add macdev to /etc/hosts (sudo)","fixes":["/etc/hosts entry"],"sudo":true}],"backups":"/Users/you/.local/state/benchbar/backups","log":"/Users/you/.local/state/benchbar/logs/20260926-101500-4242.log"}
{"event":"step","action":"build","status":"running","message":"bench build"}
{"event":"step","action":"build","status":"done","message":"bench build"}
{"event":"step","action":"hosts_entry","status":"running","message":"add macdev to /etc/hosts (sudo)"}
{"event":"step","action":"hosts_entry","status":"skipped","message":"[WARN] skipped without sudo; run: benchbar repair --bench-dir /Users/you/frappe-bench (adds '127.0.0.1 macdev' inside the benchbar block)"}
{"event":"done","exit_code":0,"log":"/Users/you/.local/state/benchbar/logs/20260926-101500-4242.log"}
EventFields
planactions[] with id (a repair action), label, fixes (the doctor checks it fixes), sudo (needs a password: skipped without a terminal, or asked for in a macOS dialog under BENCHBAR_SUDO=gui, see the privileged steps); dry_run; backups (the backup root); log
stepaction, status (running, then done, skipped or failed), message (for failed and skipped, the CLI’s [FAIL] or [WARN] line)
doneexit_code (0 when every check passes afterwards), log

repair --dry-run --json prints only the plan line and changes nothing. Without --yes (and without --dry-run) nothing is applied: the plan is printed, then done with exit code 1, because the question cannot be answered. An empty actions means nothing needs repairing.

benchbar install --json

Since 0.8 the done line also carries changed, warnings, next_actions and state_after (done fields); adopt the same.

Added in 0.8. A stream, like pull --json: one JSON object per line on stdout as the run goes, the human text in the run’s log (logs/<date>-<time>-<pid>.log in benchbar’s state folder). Every line carries schema_version, cli_version and event. The BenchBar app’s New Bench page reads it.

The stream is only valid with --yes (or with --dry-run): no question can be answered on it, so install --json without either prints one done line with exit 1 and an error, and changes nothing. Every value install would ask for comes as a flag or from the environment: --bench-dir, --profile, --bundle, --site, --port-offset, ADMIN_PASSWORD (the new site’s Administrator password; required unless the site exists) and the optional MARIADB_ROOT_PASSWORD. A missing ADMIN_PASSWORD is refused the same way, before anything runs. stdin is never read.

The stream never prompts for a password. Without BENCHBAR_SUDO=gui, a cached sudo credential or a NOPASSWD rule is used (sudo -n true); otherwise the privileged steps are skipped with their command, exactly like a cancelled dialog (see the privileged steps). On Linux the apt step of phase 00 cannot be skipped: without a cached credential the stream ends with done and exit 1, saying sudo is needed.

{"schema_version":1,"cli_version":"0.8.0","event":"plan","bench":"/Users/you/frappe-bench","site":"macdev","profile":"v15-lts","team_profile":null,"bundle":"minimal","port_offset":0,"web_url":"http://macdev:8000","dry_run":false,"sudo_mode":"gui","steps":[{"n":null,"id":"wkhtmltopdf_install","name":"Install the patched wkhtmltopdf package","sudo":true,"will_run":true},{"n":null,"id":"hosts_entry","name":"Add 127.0.0.1 macdev to /etc/hosts","sudo":true,"will_run":true},{"n":1,"id":"system_deps","name":"System dependencies (00-mac-system-deps.sh)","sudo":false,"will_run":true},{"n":2,"id":"bench_site","name":"Bench and site (01-install-bench-and-site.sh)","sudo":false,"will_run":true},{"n":3,"id":"service","name":"Background service","sudo":false,"will_run":true}],"log":"/Users/you/.local/state/benchbar/logs/20261010-101500-4242.log"}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":null,"id":"wkhtmltopdf_install","parent":null,"name":"Install the patched wkhtmltopdf package","status":"running"}
{"schema_version":1,"cli_version":"0.8.0","event":"progress","step":"wkhtmltopdf_install","label":"download wkhtmltopdf 0.12.6-2 (about 50 MB)","elapsed":10,"bytes":31457280,"total":null}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":null,"id":"wkhtmltopdf_install","parent":null,"name":"Install the patched wkhtmltopdf package","status":"done","secs":41}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":null,"id":"hosts_entry","parent":null,"name":"Add 127.0.0.1 macdev to /etc/hosts","status":"running"}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":null,"id":"hosts_entry","parent":null,"name":"Add 127.0.0.1 macdev to /etc/hosts","status":"skipped","secs":6,"message":"[WARN] the password dialog was cancelled; the line was not added","command":"benchbar site hosts --bench-dir /Users/you/frappe-bench"}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":1,"id":"system_deps","parent":null,"name":"System dependencies (00-mac-system-deps.sh)","status":"running"}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":null,"id":"python","parent":"system_deps","name":"PYTHON","status":"running"}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":null,"id":"python","parent":"system_deps","name":"PYTHON","status":"done","secs":3}
{"schema_version":1,"cli_version":"0.8.0","event":"step","n":1,"id":"system_deps","parent":null,"name":"System dependencies (00-mac-system-deps.sh)","status":"done","secs":95}
{"schema_version":1,"cli_version":"0.8.0","event":"done","exit":0,"bench":"/Users/you/frappe-bench","site":"macdev","url":"http://macdev:8000","skipped":[{"id":"hosts_entry","command":"benchbar site hosts --bench-dir /Users/you/frappe-bench"}],"fix":null,"log":"/Users/you/.local/state/benchbar/logs/20261010-101500-4242.log"}
EventFieldsNotes
planbench, site, profile (the built in profile it runs on), team_profile (string or null), bundle, port_offset (the port block the bench gets), web_url, dry_run, sudo_mode (terminal, or gui under BENCHBAR_SUDO=gui), steps[], blockers[], warnings[], logonce, first. blockers[] is {id, message, fix} per thing that would stop the run before it changes anything (the error_id values above); empty on macOS and on a free Linux machine. warnings[] is {id, message, fix} per thing the plan shows and the run goes on from, next to blockers[] (empty on macOS and on a healthy machine; Linux only): wsl_memory_low (WSL has less than about 5.5 GB), wsl_disk_low (the Windows drive has less than 15 GB free), and a host that did not answer within 10 seconds, after one retry: pypi_unreachable, npm_registry_unreachable, nodejs_unreachable, astral_unreachable and apt_mirror_unreachable (the first http or https archive in /etc/apt; a file: or mirror+file: one is not probed, and curl does not know apt’s own proxy, so it only warns). Pass --offline to skip the host probes. steps[] lists the two privileged steps first (n null, sudo true, will_run false when nothing needs doing: the patched package is in place, the line is in /etc/hosts), then the three numbered steps of the terminal output
stepn, id, parent, name, status, and on the end of a step secs; message for failed, skipped and warning (the CLI’s [FAIL] or [WARN] line); command for a skipped privileged step (what to run by hand)status is running, then done, unchanged, skipped, warning or failed. A step with a parent is a section of that phase script (parent is system_deps or bench_site) or an action of the service step (parent is service, the id is a repair action); its n is null
progressstep, label, elapsed (seconds), bytes and total (int or null)every 10 seconds while a long command runs (a download, bench init, bench get-app, bench build, bench new-site); bytes only for a download
doneexit, bench, site, url (null unless exit is 0), skipped[] (id, command of every privileged step that was skipped), fix (string or null), log, and error (only for a refusal before the plan)always the last line, also after a failure or a signal (exit is then 128 plus the signal, 143 for SIGTERM, and a step that was running gets no end line). exit 2: the MariaDB root password is unknown, fix says what to pass (MARIADB_ROOT_PASSWORD); run again with it in the environment

Section ids of the phase scripts: profile, system, plan, dry_run, python, node, database, redis, pdf, build_deps, shell_config, summary, ready, pending_manual_steps (phase 00; on Linux 00-linux-system-deps.sh adds apt_packages and has no build_deps); profile, advanced_version_mode, precheck, inputs, plan, verify_db_credentials, pipx, bench_cli, bench_init, get_apps, create_site, verify_site, install_apps_on_site, ready (phase 01). They are the section headings of the terminal output in lowercase with _, so a reader should show name and treat an id it does not know as any other section.

install --dry-run --json prints the plan line, then done with exit 0 and "dry_run":true, and changes nothing; the human plan goes to the log.

The privileged steps and BENCHBAR_SUDO=gui

The wkhtmltopdf package and the /etc/hosts line are the only things that run as root. In a terminal the run asks for sudo once up front. With BENCHBAR_SUDO=gui in the environment (the BenchBar app sets it for an install, adopt, repair or site hosts it started from a sheet the user confirmed), each of the two runs as one script through osascript ... with administrator privileges: macOS shows its own password dialog with the step’s name, benchbar never sees the password, and there is no cached credential afterwards. At most two dialogs per run. A cancelled dialog makes that step skipped with its command, and the run goes on; a step that failed behind its dialog is not asked again by a later pass of the same run. Only the value gui switches the mode, on macOS (on Linux it is ignored). Rosetta 2, when the package needs it and it is missing, is installed by the package’s own script, in the same dialog. Without gui, install --json and adopt --json never prompt: they use sudo only when it needs no password (a cached credential, a NOPASSWD rule) and skip the steps otherwise.

The commands that read BENCHBAR_SUDO: install, adopt, repair (the hosts_entry and wkhtmltopdf_install actions), site hosts, site add, ports setup and ports apply. ports apply puts the missing hosts lines of every bench of the batch in one dialog (titled Add 127.0.0.1 lines for N sites to /etc/hosts); if it is cancelled, each bench’s setup prints benchbar site hosts --bench-dir PATH as its manual step and the run goes on. site drop still needs a terminal for the line it removes.

BENCHBAR_SUDO=env (Linux)

On Linux, a program without a terminal (the Windows tray, an agent) passes the user’s sudo password in BENCHBAR_SUDO_PASSWORD with BENCHBAR_SUDO=env. The CLI takes it out of its environment before anything else runs (it starts itself once more without the variable, so the running process has no copy in /proc/PID/environ), checks it once with sudo -k and sudo -S -v before any change, and then runs its sudo steps without a prompt. A wrong password ends the run with exit 1 and error_id sudo_password_wrong. The password never goes into arguments, bash -x output, the run log or a child process: in install only phase 00 gets it, on a file descriptor. Every command forgets it, and drops the sudo credential, when its sudo steps are done, before any bench, pip or npm step runs. Without a password and without a terminal, install --json with BENCHBAR_NONINTERACTIVE=1 names BENCHBAR_SUDO_PASSWORD in missing; other commands skip their sudo step with a warning. The commands that read it: install, adopt, repair, service, site add and ports apply. On macOS it is ignored.

benchbar adopt PATH --json

Added in 0.8, the same stream as install --json. Without --yes (or --dry-run) it is refused with one done line. The plan carries bench, site, profile, port_offset, ports_move (true when adopt moves the bench to another port block with bench set-config -g), dry_run, sudo_mode, steps[] and log. Its steps are the service actions it applies, numbered from 1 as in the terminal output (id a repair action, sudo true for hosts_entry), and they stream as step events without a parent. done has exit, bench, site, url, skipped[], fix and log. An empty steps means the bench is already set up.

benchbar doctor --prerequisites --json

Added in 0.8. What a Mac needs before install, without a bench: the BenchBar app’s Check Your Mac page. --bench-dir PATH names the folder a new bench would go to (default ~/frappe-bench); it does not have to exist.

{"schema_version":1,"cli_version":"0.8.0","bench":"/Users/you/frappe-bench","prerequisites":[{"id":"apple_silicon","label":"Apple Silicon","level":"ok","message":"arm64","fix_command":null},{"id":"homebrew","label":"Homebrew","level":"fail","message":"brew was not found","fix_command":"/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""}],"summary":{"ok":7,"warn":0,"fail":1}}
idChecksLevels
apple_siliconuname -m is arm64ok, fail
macos_versionmacOS 14 or laterok, fail
command_line_toolsxcode-select -p names a folder that existsok, fail (fix xcode-select --install)
homebrewbrew on PATH or in /opt/homebrew/binok, fail (fix: the official install command)
disk_freefree space on the volume of $HOME; the check carries free_gbok from 20 GB, warn from 10 GB, fail below
bench_folderthe folder is a valid bench path and not under iCloud Drive, Desktop or Documentsok, warn (Desktop, Documents), fail (iCloud Drive, a path benchbar refuses)
cleanmymacas doctor’s cleanmymac check, for that folderok, warn
moleas doctor’s mole check, for that folderok, warn
default_portsports 8000, 9000, 11000 and 13000 are free; the check carries port_offset, the block install would give a new benchok, warn (taken: the new bench gets port_offset), fail (no block up to the last offset is free; port_offset is null)

Every object has the fields of a doctor check (id, label, level, message, fix_command), and every check that is not ok has a fix_command: the command to run, or a plain instruction where there is none (“BenchBar needs an Apple Silicon Mac”, “update macOS in System Settings, Software Update”, “free space on the volume of …”).

On Linux (Ubuntu 24.04, WSL too) the list is its own, in this order: linux_distro, architecture, regular_user, sudo (installed, and the user is in the sudo or admin group; the check never runs sudo), apt (a mirror answers; unreachable is a warn), systemd (PID 1; carries enabled), linger (carries enabled), memory (warn below 3500 MB, fail below 1800 MB; carries total_mb), disk_free, bench_folder, mariadb_password (warn with needs_password when a running MariaDB has a root password benchbar does not know) and default_ports.

Exit 1 when one is fail. benchbar doctor --prerequisites prints the same list for a person. A plain doctor does not print it (its WARN and FAIL lines promise a fix line and its exit code the state of the bench); doctor --json of a bench carries the same array as prerequisites next to checks, not counted in summary or in the exit code.

benchbar app list --json

Added in 0.5. Every app of the bench: the lines of sites/apps.txt in order, then any git app in apps/ that is not listed. The sites come from bench --site S list-apps --format json (15 seconds per site), cached per bench; --no-sites reads only the cache, so it never needs MariaDB.

{"schema_version":1,"cli_version":"0.5.0","bench":"/Users/you/frappe-bench","profile":"v15-lts",
"sites_checked_at":"2026-09-25T10:00:00Z","sites_error":null,
"apps":[{"name":"erpnext","in_apps_txt":true,"repo":"https://github.com/frappe/erpnext","remote":"upstream",
"branch":"version-15","policy_branch":"version-15","commit":"b5f784612d5b7969b72848dda5b22f10d3a8f764",
"dirty":false,"shallow":true,"version":"15.115.0","sites":["macdev"]}]}
FieldTypeNotes
sites_checked_atstring or nullwhen the site lists were last read from bench
sites_errorstring or nullwhy the last read failed for a site (MariaDB down); its apps come from the previous read
apps[].in_apps_txtboolfalse for a git app that is only a folder (doctor warns)
apps[].repostring or nullthe URL of the remote the branch follows (else upstream, else the first), without a user name or token
apps[].remotestring or nullthat remote’s name
apps[].branchstring or nullnull on a detached HEAD or without git
apps[].policy_branchstring or nullthe branch config/apps.tsv (or the profile, for frappe) names
apps[].commitstring or nullthe full HEAD commit
apps[].dirtybooltracked files have local changes (git status --porcelain -uno)
apps[].shallowboola shallow clone (bench’s shallow_clone)
apps[].versionstring or nullfrom sites/apps.json
apps[].sitesarray of stringsthe sites that have the app installed
apps[].focus, focus_pin, focus_reasons, requires, needed_by, upstream, behind, behind_daysadded in 0.6, the same fields as app focus

benchbar app focus --json

Added in 0.6. Every app of the bench, whether it is a focus app (one you work on) and why, what it needs, which focus apps need it, and how far it is behind its remote branch. Local reads only; --fetch fetches the dependencies of the focus apps first (so does doctor --fetch; nothing fetches without the flag). fetched_at is benchbar’s last such fetch.

{"schema_version":1,"cli_version":"0.6.0","bench":"/Users/you/frappe-bench","focus_days":14,"fetched_at":"2026-09-29T08:00:00Z",
"apps":[{"name":"exponent_ecr","focus":true,"focus_pin":"auto","focus_reasons":["your commit 2 day(s) ago"],"requires":["exponent_custom_v1"],
"needed_by":[],"upstream":"upstream/develop","behind":0,"behind_days":0},
{"name":"exponent_custom_v1","focus":false,"focus_pin":"auto","focus_reasons":[],"requires":[],
"needed_by":["exponent_ecr"],"upstream":"upstream/develop","behind":30,"behind_days":12}]}
FieldTypeNotes
fetched_atstring or nullthe last fetch of the dependencies that worked
focus_daysnumberhow recent a commit of yours must be to count
apps[].focusboola focus app: pinned so, or (pin auto) with a reason
apps[].focus_pinstringauto, focus (app focus NAME) or ignore (app unfocus NAME)
apps[].focus_reasonsarray of stringspinned, local changes, on BRANCH, not POLICY, your commit today or your commit N day(s) ago; empty when not a focus app
apps[].requiresarray of stringsrequired_apps from the app’s hooks.py, frappe left out
apps[].needed_byarray of stringsthe focus apps that need it, directly or through another app; empty for a focus app
apps[].upstreamstring or nullREMOTE/BRANCH the app’s branch follows; null on a detached HEAD
apps[].behindnumber or nullcommits on the upstream (as last fetched) that HEAD lacks, counted along the upstream’s first parent line, so the commits a merge brings in count as the merge (0.8); null when unknown (never fetched)
apps[].behind_daysnumber or nullthe age in days of the first of those commits (0.8: the first on the first parent line, never a commit a merge brought in)

app focus NAME [--auto] --json and app unfocus NAME --json print {"schema_version","cli_version","bench","app","pin","focus","reasons"}.

benchbar app update NAME --dry-run --json

Since 0.8 app update NAME --json without --dry-run streams: the plan line (this document’s fields), a step per plan step, and a done with updated and the done fields. --dry-run --json is still this one document; --dry-run --jsonl is the same fields as a plan line, then done.

Added in 0.5. The plan of an update, after git fetch (which changes only the app’s .git). Without --dry-run, --json streams (see the top of this section).

{"schema_version":1,"cli_version":"0.5.0","bench":"/Users/you/frappe-bench","app":"erpnext","remote":"upstream","branch":"version-15",
"from":"a1b2c3d...","to":"b5f7846...","commits":[{"sha":"b5f7846","subject":"fix: ..."}],"commits_total":12,
"newer_commits":0,"pending":null,"sites":["macdev"],"skip_backup":false,
"steps":[{"name":"Back up macdev","command":"bench --site macdev backup","kind":"backup","target":"macdev"},{"name":"Fast forward","command":"git -C apps/erpnext merge --ff-only b5f784612d5b","kind":"fast_forward","target":""}]}
FieldTypeNotes
from, tostringfull commits; equal when there is nothing to take (also when the app is ahead of its remote)
commitsarraynewest first, at most 30, sha short
commits_totalnumberall commits in from..to
sitesarray of stringsthe sites that have the app: each is backed up (unless skip_backup) and migrated
stepsarrayin order: Back up S, Fast forward, Python requirements, Node requirements, Migrate S, Build, and Restart when the bench runs; empty when there is nothing to do. Each has kind (backup, fast_forward, requirements_python, requirements_node, migrate, build, restart) and target (a site, the app, or "") besides name and command
pendingobject or nullthe record of an earlier run of this update that stopped part way (the same object status --json lists in pending_operations, plus schema_version, started_at), or null. With a record, from and to are the range that run reviewed, steps are only the steps it did not finish (the run takes them even when the app is already at to), and commits is from..to
newer_commitsnumberwith a record: commits the remote has beyond to; they wait for the next run. 0 otherwise

An app moved by hand since the record was written (its HEAD is neither from nor to; or, once the fast forward is done, not to) exits 1 and names --discard-pending, which drops the record (and logs what it dropped) and stops: nothing else runs.

A dirty tree, a detached HEAD or a diverged branch exits 1 with the reason as text.

benchbar app add URL --dry-run --json

Since 0.8 the result of --apply TOKEN --yes --json (one line) also carries the done fields; with --jsonl it is a done line with the same fields.

Added in 0.6.0. The plan of an app add, read only, with the token that --apply TOKEN --yes (and benchbar_app_add over MCP) needs. The text goes to stderr. A refusal the plain app add also makes (an unknown name, a URL with a token in it, an unknown site, the app on another branch) exits 1 with the reason as text; anything else is a plan, with can_apply saying whether it can run.

{"schema_version":1,"cli_version":"0.6.0","bench":"/Users/you/frappe-bench","profile":"v15-lts",
"target":"https://github.com/acme/acme_crm","app":"acme_crm","package":"acme_crm",
"repo":"https://github.com/acme/acme_crm","branch":"main","commit":"9b1d2c...40 hex characters","commit_source":"branch","branch_source":"remote_default",
"present":false,"reachable":true,
"sites":[{"name":"macdev","installed":false}],"sites_error":null,
"required_apps":[{"name":"acme_base","required_by":"acme_crm","present":false,"resolves":true,
"source":"apps_tsv","repo":"https://github.com/acme/acme_base","branch":"main","commit":"4e07aa..."}],
"missing_required":["acme_base"],"order":["acme_base"],
"steps":[{"kind":"clone_required","name":"Clone acme_base","command":"bench get-app --skip-assets --branch main https://github.com/acme/acme_base","note":"..."},
{"kind":"clone","name":"Clone acme_crm","command":"bench get-app --skip-assets --branch main https://github.com/acme/acme_crm","note":"..."},
{"kind":"build","name":"Build","command":"bench build --apps acme_base,acme_crm","note":"..."},
{"kind":"install","name":"Install on macdev","command":"bench --site macdev install-app acme_crm","note":"..."},
{"kind":"restart","name":"Restart","command":"benchbar restart","note":"only when the bench is running, ..."}],
"errors":[],"changes":true,"can_apply":true,"reason":null,
"token":"3f9c0e...64 hex characters"}
FieldTypeNotes
targetstringwhat was asked for, without a user name or token
appstringthe app name: --name, else the package folder that holds hooks.py, else the repo name
packagestring or nullthat package folder; null when hooks.py could not be read
repostringthe URL get-app gets
branchstring or nullnull when it could not be told (then errors says so)
commitstring or nullthe commit the plan read hooks.py from: the pin (always the full hash) when --commit is given, else the branch tip; --apply stops before build and install when get-app checks out another one, and when a pinned commit is not reached by the clone
commit_sourcestringpin (--commit; for an app already in the bench, it is at the pin) or branch
branch_sourcestring or nullgiven (--branch), policy (config/apps.tsv or the team profile), remote_default (the remote’s HEAD) or present (the branch of the app already in the bench)
presentboolthe bench already has the app; then no clone and no build, only installs
reachablebool or nullgit could read the repo without a prompt, within the timeout; null when the app is present (nothing is fetched)
sites[]arraythe target sites (--site, --all-sites, --install-on) and whether each has the app already (in a batch: the union over the apps, installed true when no app of the batch needs an install there)
apps[]arraypresent only when several apps were given: one entry per target, in the order given, with its own app, package, target, repo, branch, branch_source, commit, commit_source, present, reachable, install_on (the sites of its --install-on, empty when it has none), sites[] (its own sites and whether it is installed there) and required_apps (the names its hooks.py requires). The fields above describe the first target; required_apps[], missing_required, order and steps[] cover the whole batch
sites_errorstring or nullas in app list --json
required_apps[]arrayevery app hooks.py requires, followed through the ones that get cloned; present in the bench, resolves through source (apps_tsv or team_profile) with its repo, branch and commit
missing_requiredarray of stringsthe required apps the plan clones or cannot resolve
orderarray of stringsthe apps the plan clones, each after the apps it requires (ties keep the order the plan always had), the apps being added after the ones they need when they are cloned; the required apps of every target are one graph, an app two targets require is cloned once. A cycle in required_apps is an errors entry, required_apps cycle: a -> b -> a, with can_apply false
reasonstring or nullset when a record of an earlier, unfinished add of this app is merged into the plan (the build, installs and restart it did not finish are steps, changes is true); otherwise null
steps[]arrayin the order --apply runs them; kind is clone_required, clone, requirements_python (only when an earlier run left a cloned app without its pip install), build (one for every app that is cloned), install (one per app and site, site by site, each site in dependency order; named Install APP on SITE when several apps were given) or restart (once, run only when the bench is running); note says what else the step does, for install that it changes the site’s database like a migrate of these apps
errorsarray of stringswhy the plan cannot run: an unreadable repo, a missing branch, no hooks.py, a required app nothing resolves
changesboolfalse when there is nothing to do
can_applyboolfalse when errors is not empty
tokenstringSHA-256 of the plan (the commits included, so a branch that moves makes it stale) and of the bench’s sites/apps.txt, apps/ folders and site list

benchbar app add URL --apply TOKEN --yes --json, the result: {"schema_version", "cli_version", "bench", "app", "branch", "commit", "commit_source", "token", "applied": true, "ok", "steps": [{"kind", "name", "status", "reason"}], "apps": [...], "required_apps": [...]}. apps[] has one entry per target (always, also for one app) and required_apps[] one per required app that was cloned: {"app", "cloned", "clone", "build", "installs": [{"site", "status", "migrate", "reason"}]}. cloned is true when this run cloned the app; clone and build are the status of that step (null when the app had none, for example build of an app that was already there); each install has the status of its step and the same status as migrate, because install-app is what runs the app’s patches and syncs its DocTypes (there is no separate migrate step). An install skipped because an app it requires failed to install on that site has reason after failed install of APP. Where status is done, failed, skipped (after a failed step it depends on: clone, then build, then install and restart; or a restart of a stopped bench) or pending. reason is after failed <kind> for a step skipped because of a failure, else null. A failed or skipped step stays in the app’s pending record, which the next plan merges. Exit 0 when ok. A stale token or a plan that cannot run exits 1 with no JSON and the reason on stderr.

benchbar lock check --json

Added in 0.5. The bench compared with its lockfile (benchbar.toml). Read only: no network, no database (a site’s apps come from the cache app list fills), only bench --version for the bench CLI. Exit 1 on any drift; the JSON is still printed.

{"schema_version":1,"cli_version":"0.5.0","bench":"/Users/you/frappe-bench","lock_file":"/Users/you/frappe-bench/apps/acme/benchbar.toml",
"in_sync":false,
"drift":[{"kind":"commit_behind","app":"erpnext","site":null,"expected":"b5f7846","actual":"a1b2c3d","level":"warn","fix_command":"benchbar lock apply"}],
"summary":{"ok":12,"warn":1,"fail":0}}
kindlevelMeaning
profile_mismatchwarnthe lock’s [bench] profile differs from the bench’s (a team profile’s base)
bench_version_mismatchwarnthe frappe-bench CLI version differs
app_missingfaila lock app has no folder or no apps.txt line
app_extrawarnan apps.txt app the lock does not name
repo_mismatchwarnthe app’s remote is another repo (HTTPS and SSH spellings of one repo compare equal)
branch_mismatchwarnanother branch, or a detached HEAD (actual is detached)
commit_behindwarnthe pinned commit is ahead of the checkout; lock apply fast forwards
commit_aheadwarnthe checkout has commits after the pin; lock apply leaves it
commit_divergedwarnneither contains the other; lock apply leaves it
commit_unknownwarnthe pin is not in the local history yet; lock apply fetches it
dirtywarntracked files have local changes
site_missingwarna lock site has no folder
site_app_missingwarnthe site lacks an app the lock lists for it (app and site are both set)

expected and actual are strings or null; commits are 7 characters. summary.ok counts the lock’s apps, sites and bench fields without drift. Doctor runs the same comparison as lock_drift (without the bench version) and lock_parse, both in group bench with action: null.

list --json gains benches[].lock_file: the path lock check would use for that bench (remembered from --lock, or <bench>/benchbar.toml when it exists), else null.

benchbar profile list --json

Added in 0.5. The built in profiles, then every team profile file on the lookup path (~/.config/benchbar/profiles/, then each subscription in subscribe order, then each folder of BENCHBAR_PROFILE_PATH), invalid ones included so a reader can show why. Read only and offline: how far a subscription is behind comes from its last fetch.

{"schema_version":1,"cli_version":"0.6.0","profiles":[
{"name":"v15-lts","kind":"builtin","source":"builtin","source_url":null,"subscription":null,"shadowed_by":null,"schema":null,
"file":"/Users/you/benchbar/config/release-profiles.tsv","base":null,
"label":"Frappe/ERPNext v15 LTS","frappe_branch":"version-15","valid":true,"error":null},
{"name":"acme","kind":"team","source":"subscribed","source_url":"git@github.com:acme/bench-config.git",
"subscription":{"repo":"git@github.com:acme/bench-config.git","dir":"/Users/you/.config/benchbar/sources/acme-bench-config",
"behind":2,"days":5,"fetched_at":"2026-09-29T10:00:00Z"},"shadowed_by":null,"schema":2,
"file":"/Users/you/.config/benchbar/sources/acme-bench-config/profiles/acme.toml","base":"v15-lts",
"label":"Acme ERP","frappe_branch":null,"valid":true,"error":null}]}
FieldTypeNotes
kindstringbuiltin or team
sourcestringbuiltin, user (a file in ~/.config/benchbar/profiles) or path (a BENCHBAR_PROFILE_PATH folder); 0.6 adds imported (a file there that profile import wrote) and subscribed
source_urlstring or null0.6: the URL or path an imported file came from, or a subscription’s repo URL; null otherwise
subscriptionobject or null0.6: for a subscribed profile, repo, dir, behind (commits the clone lacks, int or null), days (age of the oldest of them, int or null) and fetched_at (the last successful fetch, or null)
shadowed_bystring or null0.6: the file that hides this one (an earlier file of the same name, or the built in profiles’ file)
schemaint or null0.6: the file’s schema (1 when it has none); null for built in profiles and invalid files
filestringwhere it was read from
basestring or nullthe built in profile a team profile builds on; null for built in ones and invalid files
labelstring or nullthe built in label, or a team profile’s description
frappe_branchstring or nulla team profile’s override, else the built in branch
validboolfalse when install --profile NAME would refuse it
errorstring or nullwhy: a parse error (FILE:LINE: not supported: ...), a name that shadows a built in profile, or a name hidden by an earlier file
python, node, mariadbstring or null0.8: the versions the profile brings ("3.11", "22", "10.11"), a team profile’s from its base; null for an invalid file

0.8 adds bundles at the top: the app bundles install --bundle takes, each with name, label, apps (array of app names) and description, from config/app-bundles.tsv.

Profile sharing

Added in 0.6. With --json, each of these prints one document on stdout and every human line on stderr. --plan is read only (it may ask git and the network, never writes) and takes no lock. A write needs --yes: a question that cannot be answered counts as no and exits 1. A refusal or error exits 1; profile check exits 0 whatever it finds. reachable is true, false (git answered no: no access, no such repo or branch) or null (offline or timed out, 10 seconds per repo), with reason saying why when it is not true.

benchbar profile export NAME --plan --json

{"schema_version":1,"cli_version":"0.6.0","name":"acme","base":"v15-lts","apps":[
{"name":"acme_ecr","repo":"git@github-work:acme/acme_ecr.git","exported_repo":"git@github.com:acme/acme_ecr.git",
"current_branch":"wip","exported_branch":"develop","default_branch":"develop","branch_verified":true,
"access":"private","requires":["acme_base"],"keep":true}],
"warnings":["acme_ecr: git@github-work:acme/acme_ecr.git is written as git@github.com:acme/acme_ecr.git"],
"digest":"5d41aa...64 hex characters"}
FieldTypeNotes
apps[].repostringthe URL in the profile
apps[].exported_repostringthe URL written: SSH alias resolved with ssh -G, user info removed
apps[].current_branchstringthe branch in the profile
apps[].exported_branchstringthe branch written: --branch APP=BR, else the repo’s default branch; an app of config/apps.tsv on the base’s release branch (erpnext on version-15) keeps it
apps[].default_branchstring or nullwhat the remote’s HEAD points at; null when git could not tell
apps[].branch_verifiedboolthe exported branch exists on the remote
apps[].accessstringpublic (a stranger can read it over https), private, personal (private, and its GitHub owner is a user, not an organisation) or unknown (offline, or not an https or SSH URL)
apps[].requireslist of stringsfrom the profile, else from the app’s hooks.py in the bench (--bench-dir)
apps[].keepboolfalse for an app given to --drop
warningslist of stringsfor a person: rewritten URLs, unverified branches, personal repos, drops that are refused
digeststring0.6: SHA-256 of what the plan read: the profile file and each app’s URLs, branches, access and requires; the same with or without --branch and --drop

profile export NAME --out FILE [--branch APP=BR]... [--drop APP]... --yes --json writes the file and prints {"path","apps","dropped"}: the path, how many apps it holds and the dropped ones. Dropping an app that a kept app requires is refused with exit 1 and {"error":"...","blocked":[{"app":"acme_base","required_by":["acme_ecr"]}]}. With --expect DIGEST it refuses (exit 1, nothing written) when the plan no longer matches that digest. BenchBar passes the digest and every kept app’s branch, so it writes exactly what the sheet showed.

benchbar profile import SRC [--as NAME] --plan --json

{"schema_version":1,"cli_version":"0.6.0","name":"acme","source":"https://github.com/acme/config/blob/main/acme.toml",
"exists":true,"diff":"@@ -3 +3 @@\n-description = \"Acme\"\n+description = \"Acme ERP\"","base":"v15-lts",
"apps":[{"name":"acme_ecr","repo":"git@github.com:acme/acme_ecr.git","branch":"develop","access":"private","requires":["acme_base"]}],
"check":{"repos":[{"app":"acme_ecr","repo":"git@github.com:acme/acme_ecr.git","reachable":false,"reason":"Permission denied (publickey)."}]},
"skipped_apps":["acme_ecr"],"digest":"c2a1f0...64 hex characters"}

exists is whether ~/.config/benchbar/profiles/NAME.toml is there; diff is the unified diff against it (null when there is none or they are equal). apps[].access is null when the file does not say. skipped_apps are the apps install --profile would leave out: the unreachable ones and every app that requires one. digest is the SHA-256 of the file the import would write. With --yes --json it writes and prints {"name","path","source"}; with --expect DIGEST as well, it refuses (exit 1, nothing written) when the source changed since that plan.

benchbar profile subscribe GIT_URL [--plan|--yes] --json

{"repo","dir","profiles"}: the URL, the clone’s folder (~/.config/benchbar/sources/OWNER-REPO) and the valid profile names in it. Subscribing to a URL already subscribed prints the same and changes nothing.

benchbar profile update NAME|--all --plan --json

{"schema_version":1,"cli_version":"0.6.0","updates":[
{"name":"acme","kind":"subscribed","behind":2,"diff":"diff --git a/profiles/acme.toml ..."}],
"digest":"77e3b9...64 hex characters"}

kind is imported or subscribed; behind is the new commits of a subscription (null for an import); diff is null when there is nothing new. digest covers what the plan showed: each import’s fetched file and each subscription’s upstream commit. With --yes the same document adds "applied":true (false when one of them could not be applied); --expect DIGEST refuses (exit 1, nothing changed) when the source has moved on since that plan, and a subscription fast forwards to the reviewed commit, not a newer one.

benchbar profile remove NAME --yes --json

{"name","moved_to"}: the file or subscription folder now under ~/.config/benchbar/removed/<timestamp>/.

benchbar profile check NAME --json

{"name","repos":[{"app","repo","reachable","reason","commit"}],"skipped_apps":[...],"frappe_commit","erpnext_commit"}, as in the import plan. Since 0.8 each repo carries the commit the profile pins it to (null for none), and frappe_commit and erpnext_commit are the profile’s pins for the two apps it does not list as [[apps]] (null for none). A pin is read, not tried against the server: whether the clone reaches it is checked by install, before anything is built.

benchbar pull --json

Since 0.8 the done line also carries changed, next_actions and state_after (done fields); its warnings are as before.

Added in 0.5. Unlike the commands above, pull changes things, so it streams: one JSON object per line on stdout, written as the run goes, and every human line on stderr. Use it with --yes (a gate that cannot be answered counts as no). Each line carries schema_version, cli_version and event:

{"schema_version":1,"cli_version":"0.5.0","event":"plan","source":"prod:erp.example.com","host":"prod","remote_site":"erp.example.com","remote_bench":"~/frappe-bench","from_dir":null,"bench":"/Users/you/frappe-bench","site":"erpcopy","replace":false,"backup":{"name":"20260925_020000-erp_example_com-database.sql.gz","new":false,"bytes":734003200,"age_hours":31,"encrypted":false},"encryption_key":true,"apps":[{"app":"frappe","production_version":"15.40.0","production_branch":"version-15","local_version":"15.41.0","local_branch":"version-15","status":"local newer"}],"migrate":true,"steps":["Download the backup","Restore into erpcopy","..."],"dry_run":false}
{"schema_version":1,"cli_version":"0.5.0","event":"gate","name":"apply","answer":"yes"}
{"schema_version":1,"cli_version":"0.5.0","event":"progress","file":"20260925_020000-erp_example_com-database.sql.gz","bytes":700000000,"total":734003200}
{"schema_version":1,"cli_version":"0.5.0","event":"step","n":1,"id":"download","name":"Download the backup","status":"done"}
{"schema_version":1,"cli_version":"0.5.0","event":"done","exit":0,"site":"erpcopy","url":"http://erpcopy:8000","decrypt":{"ok":12,"failed":0},"warnings":[]}
EventFieldsNotes
plansource, host, remote_site, remote_bench, from_dir, bench, site, replace, backup, encryption_key, apps, migrate, create_site, before_migrate, steps, dry_runonce, after the read only checks. backup.name, bytes and age_hours are null with --new-backup (that backup does not exist yet). encryption_key says whether production has one to carry over, never its value. Since 0.8 create_site says the target does not exist and a new_site step makes it, before_migrate is the path of the --before-migrate script or null, and migrate is false with --no-migrate. A target the restore cannot go into (a folder without a site_config.json, a bench new-site that did not finish, no MariaDB root password) ends the run before this line, in a dry run too
gatename (new_backup, apply, replace), answer (yes, no)a question the run asked. new_backup is yes only when the typed (or --confirm-site) name matches
progressfile, bytes, totalafter each downloaded file; bytes counts the files so far
stepn, id, name, statusn counts from 1 in the order of plan.steps; status is done, unchanged, skipped or failed
doneexit, site, warnings, and on success url and decryptalways the last line: also after a refusal or a failure (exit 1) and after --dry-run (dry_run: true)

apps[].status is ok, missing, skipped (--skip-app), branch differs, local older or local newer. decrypt.ok and decrypt.failed count the encrypted __Auth rows that do and do not decrypt with the site’s encryption_key; failed above 0 means stored passwords must be entered again. Step ids: new_backup, download, decrypt, local_backup, quiesce, new_site, restore, encryption_key, resume, dev_safety, skip_apps, before_migrate, migrate, clear_cache, admin_password, hosts, cleanup, verify; a run lists only the ones it needs.

No event ever holds a password, the encryption key or a token from an app’s remote URL.

benchbar report --json

Writes the redacted diagnostics zip (to ~/Desktop, or --out DIR) and prints one line on stdout; the human text goes to stderr. The BenchBar app’s Report a Bug uses it.

{"schema_version":1,"cli_version":"0.5.5","zip":"/Users/you/Desktop/benchbar-report-20260926-101500.zip","redactions":14}
FieldTypeMeaning
zipstringabsolute path of the zip just written
redactionsnumberlines on which something was replaced (a credential, the home folder, the username, a name of this Mac); REDACTIONS.txt in the zip lists them

Exit 0 when the zip was written. --json with --print exits 1.

benchbar where --json

How this CLI was installed and where its things are, since 0.7.0. Read only: it needs no bench, takes no lock and writes no log. Scripts, agents and the app can use it to tell a Homebrew install from the others instead of guessing from paths.

{"schema_version":1,"cli_version":"0.7.2","install":"app","self":"/Users/you/.local/state/benchbar/bin/benchbar","state_dir":"/Users/you/.local/state/benchbar","state_dir_real":"/Users/you/.local/state/benchbar","app_version":"0.7.2","app_path":"/Applications/BenchBar.app","handoff_from":"/opt/homebrew/opt/benchbar/bin/benchbar","handoff_from_version":"0.7.2"}
FieldTypeMeaning
installstringhomebrew (the benchbar formula), managed (the one line installer’s checkout, ~/.local/share/benchbar), app (the CLI inside BenchBar.app, 0.7.1), checkout (another git clone, such as ./benchbar in the repo) or other. Treat a value you do not know as other
selfstringthe path of this CLI that the helper block, the ~/.local/bin links and every printed fix command use. Under Homebrew it is <prefix>/opt/benchbar/bin/benchbar, which brew upgrade keeps; never a versioned Cellar path. For app it is ~/.local/state/benchbar/bin/benchbar, the link the app keeps to its CLI, or the CLI’s own path in an app that is not installed (a build from Xcode)
state_dirstringthe folder of the remembered benches, per bench settings, run logs, backups and the lock: ~/.local/state/benchbar for homebrew, managed and app (a symlink to ~/.local/share/benchbar/.benchbar when the two are on different volumes), .benchbar next to the CLI for the others, or FL_STATE_DIR when that is set
state_dir_realstringthe folder behind state_dir, with every link resolved (0.7.3). The same as state_dir unless ~/.local/state/benchbar is a link to the installer checkout’s .benchbar on another volume; the human output then shows state LINK -> REAL
app_versionstring or nullthe BenchBar app’s version, null when no app is installed
app_pathstring or nullfor app, the app this CLI is part of; otherwise the app it found first, /Applications before ~/Applications; null when none
handoff_fromstring or nullthe Homebrew or installer CLI that was run and handed off to this one (0.7.1), null when this CLI was run directly
handoff_from_versionstring or nullthe version of that copy (0.7.3), null when this CLI was run directly or that copy’s version is unknown. A copy newer than cli_version hands off to an older CLI: update the app (doctor’s cli_duplicate says so)

Exit 0. An argument other than --json exits 1.

benchbar labs --json

labs list --json is one document, with no done fields:

{"schema_version":1,"labs":[{"name":"lan-rooms","title":"...","description":"...","warning":"...","since":"0.9.0","enabled":false,"commands":["share","lan-guard"],"platforms":["macos"],"available":false}]}

commands are the top level commands the lab gates (it may be empty, or name a command this version does not have). platforms is the list the lab runs on (macos, linux, windows) and available is true when this machine is one of them (WSL counts as windows and also runs a linux lab). labs on exits 1 with “NAME is not available on PLATFORM yet” when it is not. labs status NAME --json is {"schema_version":1,"name":"lan-rooms","enabled":false} and exits 1 when off. labs on and labs off stream like site open-as: the done line carries lab, enabled and the done fields. labs on exits 2 with error “turning on an experiment is a person’s decision” when nothing can ask. Added after 0.8.1: status --json and commands --json have labs (the enabled names); commands --json also has gated ([{"name","lab"}] for a command left out because its lab is off) and a command of an enabled lab has lab.

Site backups

Since 0.8 the results of site backup and site drop (not their plans) also carry the done fields, and site drop’s plan and result default_site. --jsonl turns either into a stream whose done carries the document’s fields.

site backup, site backups and site drop (0.5.8) describe a backup the same way. A backup is the files in the site’s backup folder that share one timestamp:

{
"stamp": "20260929_101500",
"time": "2026-09-29T04:45:00Z",
"path": "/Users/you/frappe-bench/sites/macdev/private/backups/20260929_101500-macdev-database.sql.gz",
"database": "/Users/you/frappe-bench/sites/macdev/private/backups/20260929_101500-macdev-database.sql.gz",
"files": "/Users/you/frappe-bench/sites/macdev/private/backups/20260929_101500-macdev-files.tar",
"private_files": "/Users/you/frappe-bench/sites/macdev/private/backups/20260929_101500-macdev-private-files.tar",
"config": "/Users/you/frappe-bench/sites/macdev/private/backups/20260929_101500-macdev-site_config_backup.json",
"size_bytes": 5242880,
"with_files": true,
"encrypted": false,
"partial": false
}
FieldMeaning
stampthe timestamp at the start of the file names, in the site’s time zone
timewhen the database file was written, UTC
paththe database file, the one a restore needs (else the first file of the set)
database, files, private_files, configeach part, null when the set has none
size_bytesall parts together
with_filesthe set has the public or private files
encrypted, partialbench’s encrypted and partial backups (-enc, -partial)

benchbar site backups NAME --json: {"schema_version", "cli_version", "bench", "site", "folder", "backups": [backup, ...]}, newest first.

benchbar site backup NAME --json: {"schema_version", "cli_version", "bench", "site", "dry_run", "backup": backup}; backup is null in a dry run.

benchbar site drop NAME --confirm-site NAME --dry-run --json, the plan:

{
"schema_version": 1, "cli_version": "0.5.8",
"bench": "/Users/you/frappe-bench", "site": "bbtest.localhost",
"dry_run": true, "is_default": false, "new_default": null,
"steps": [
{"title": "Back up bbtest.localhost with files, drop its database and user, move the folder to archived/sites", "command": "bench drop-site bbtest.localhost", "needs_password": false},
{"title": "Remove '127.0.0.1 bbtest.localhost' from /etc/hosts", "command": "sudo, backup first", "needs_password": true}
]
}

And the result, without --dry-run:

FieldMeaning
droppedtrue; a failed drop exits 1 with no JSON
archived_paththe site folder in archived/sites/, null if bench put it elsewhere
backupthe backup bench took before dropping (inside the archived folder), or null
new_defaultthe site that became the default, or null
hosts_removedthe /etc/hosts line was removed
manual_stepthe command that removes the hosts line by hand when benchbar could not (no terminal for sudo, a line outside benchbar’s block), else null

benchbar site restore --json

Added in 0.8. The plan of a restore from a backup set, read only, with a token. --apply TOKEN --yes runs exactly that plan:

{
"schema_version": 1, "cli_version": "0.8.0",
"bench": "/Users/you/frappe-bench", "site": "acme.localhost",
"new": false, "exists": true,
"source": {
"site": "acme.localhost",
"set": { "stamp": "20260902_090000", "...": "a backup, as above" },
"restores_files": true, "encryption_key": true
},
"backup_first": { "will_run": true, "with_files": true, "folder": "/Users/you/frappe-bench/sites/acme.localhost/private/backups" },
"migrate": true, "before_migrate": null, "before_migrate_sha256": null,
"touches": ["backup", "database", "files", "site_config"],
"steps": [
{ "id": "local_backup", "name": "Back up acme.localhost with its files", "touches": ["backup"] },
{ "id": "restore", "name": "Restore 20260902_090000 into acme.localhost with its files", "touches": ["database", "files"] },
{ "id": "encryption_key", "name": "Carry the encryption key of the set over", "touches": ["site_config"] },
{ "id": "migrate", "name": "bench migrate", "touches": ["database"] },
{ "id": "clear_cache", "name": "Clear caches", "touches": ["cache"] },
{ "id": "verify", "name": "Verify acme.localhost", "touches": [] }
],
"warnings": [], "needs": [], "errors": [], "can_apply": true,
"token": "8f1c...64 hex characters"
}
FieldMeaning
site, new, existsthe target; new is --new (the site is created first, with bench new-site), exists that a site of that name is there
source.sitethe site whose backups the stamp names (--from-site, else the target); null for a path
source.setthe backup set, as in Site backups
source.restores_files--with-files was given: the public and private files are restored too
source.encryption_keythe set’s site_config_backup.json has an encryption_key, which is carried into the target (never printed)
backup_firstan existing target is backed up with its files before anything changes (will_run); folder is where the set lands
migrate, before_migrate, before_migrate_sha256migrate is false with --no-migrate; before_migrate is the path of the --before-migrate script and before_migrate_sha256 its hash (a changed script makes the token stale)
toucheswhat the run changes: backup (an existing target is backed up first), database, files, site_config, hosts for a new site whose /etc/hosts line is missing, and common_site_config when the scheduler of a running bench is paused for the restore
needsinputs a run in a terminal would ask for, for example ["MARIADB_ROOT_PASSWORD"] when none is stored. In a terminal (no --json, no --yes) the plan stays applicable; for --json it is an error as well, because nothing can answer
stepsin the order they run, each with the touches of that step. Ids: local_backup, quiesce, new_site, restore, encryption_key, resume, before_migrate, migrate, clear_cache, hosts, verify
errors, can_applywhat stops the plan (no such site, a set that is not there, an encrypted or file-less set, MariaDB down, the root password unknown to benchbar, apps the bench lacks, a hook that is not an executable file); can_apply is false when there is one. The command still exits 0 with --json
tokena hash of the plan and of what it was made against: the sites, the default site, the hook and the set’s files. --apply recomputes it and refuses a different one: The site restore plan changed since it was shown, nothing changed

The result of --apply TOKEN --yes --json:

FieldMeaning
applied, okok is false when a step failed (exit 1); the steps after it stay pending or skipped
site, new, tokenas in the plan
backupthe backup taken before an existing target was touched (a backup), null for a new site or when it did not get that far. It must be a new set with its database and both file archives, or the run stops before anything is overwritten. Put it back with site restore TARGET --from STAMP --with-files --yes
set_copyfor an existing target: the folder under the state backups that holds a copy (hard links, else copies) of the set that was restored. Bench’s own backup deletes old backups in the target’s folder, so the restore reads the copy, which stays after the run. null for a new site
steps[{"id","name","status"}], status is done, unchanged, skipped, failed or pending
verifywhat the end check found: apps (what bench --site TARGET list-apps answers), default_site (the default site after the run, which is never changed: if a step moved it, it is put back with bench use and a warning says so) and answers (the web ping of the target while the bench runs, else null)
warningsfor example migrate was skipped (--no-migrate)

Exit 0 only after the end check passed: the target answers list-apps with frappe in it, and the default site is where it was. Exit 2 is the MariaDB root password unknown to benchbar. The hook (--before-migrate) runs in the bench folder with BENCHBAR_SITE, BENCHBAR_BENCH and BENCHBAR_DB_NAME; variables named like a secret (*PASSWORD*, *SECRET*, *TOKEN*, *PASSPHRASE*, *_KEY) are removed from its environment, and a failing hook ends the run before migrate.

logs/.benchbar/state.json

Written on every transition, always by writing a temp file in the same folder and renaming it over state.json. A reader never sees half a file, but a file watcher on state.json itself breaks at the first rename: watch the logs/.benchbar/ folder instead.

{"schema_version":1,"cli_version":"0.3.0","bench":"/Users/you/frappe-bench","name":"frappe-bench","site":"macdev","label":"com.benchbar.frappe-bench","state":"running","stop_reason":null,"pid":4242,"started_at":"2026-09-23T10:00:00Z","last_exit_code":null,"web_url":"http://macdev:8000","web_ping_code":200,"updated_at":"2026-09-23T10:00:14Z","source":"runner"}

It has the core fields of status (schema_version to web_ping_code) plus:

FieldTypeNotes
updated_atstringwhen this transition was written; it does not move between transitions (the heartbeat is its own file, below)
sourcestringrunner (the launchd runner) or cli (up, down, restart)

cli_version is the version of the benchbar that wrote the transition: for source: runner, the one that wrote the runner script. Since 0.7.0 a new CLI version alone no longer rewrites the runner (doctor does not count it as outdated), so this can be older than benchbar --version.

Transitions the runner writes:

Whenstatestop_reason
the agent starts while a stop flag existsstopped or pausedfrom the flag
honcho or env/bin/python is missingpausedbroken
the runner cannot write the crash history or the stop flagpausedbroken
the crash guard tripspausedcrash
a process that is not this bench’s still holds one of its ports after the cleanuppausedport_conflict
honcho startedstartingnull
the site answered 200 (checked every 2 seconds for 4 minutes)runningnull
the runner got SIGTERM without a stop flag (logout, restart, shutdown)stoppednull
honcho exited 0 without a stop flag (0.7.3: a bench never ends on its own, so launchd restarts it)crashedcrash
benchdown stopped itstoppedmanual
honcho exited with an errorcrashedcrash

The CLI writes starting just before up and restart kick the agent, and stopped with manual after down. The state file is a hint for fast updates; status --json is the truth, because it also checks the processes and the site.

logs/.benchbar/heartbeat

Since 0.6.1 the runner rewrites this file every 30 seconds while honcho runs, starting just before it writes starting. The write is in place (no temp file, no rename), so it changes no entry of the folder and a folder watcher is not woken by it; only the transitions in state.json are. The content is the runner’s age in seconds, one line; read the file’s modification time, not the content. The file stays after the runner stops.

How a reader uses it, while state.json says running or starting:

The runner’s pidheartbeat mtimeMeaning
aliveunder 90 seconds oldfresh: state.json is the truth, no need to ask the CLI
alivemissing, 90 seconds or older, or dated more than 5 seconds in the future (a clock moved back; a beating runner rewrites it within 30 seconds)a runner from before 0.6.1 (or one that hangs): ask status --json; benchbar restart gives the bench a runner that beats
deadanythe runner is gone without writing its last state: ask status --json

benchbar doctor reads the same file (check runner_heartbeat).

Folder discovery

benchbar scan PATH --json is read only and returns a schema-version-1 object: schema_version, cli_version, root (canonical selected folder), benches (the same entries as list), and warnings (strings for skipped unreadable folders). A valid folder with no benches returns an empty array; an invalid or unreadable root exits 1. Hidden directories, symlinks, dependency/build folders, and test/fixture folders are skipped. A found bench’s children are not scanned.

benchbar register PATH ... --json validates every path, atomically remembers the canonical paths in registered-benches.txt in the state folder, then returns the normal list response. It does not create services or change the default bench. --dry-run does not write the registry. List includes these registered paths while they still identify bench directories. Registration is idempotent.

Same-named benches receive distinct launchd labels when necessary, using a canonical-path checksum suffix. An installed label owned by the same bench is retained. Clients should always use the returned label rather than deriving it from the directory name.

Sharing

benchbar share and benchbar lan-guard (reference). Every document starts with schema_version and cli_version; under --json the done fields follow. The streams (setup, start, stop, extend, lock, unlock, remove, assign, teardown, and lan-guard install, remove and allow-node) end in a done line carrying the fields shown. No document but share code --json and share invite --json ever holds the room code, and none holds a session id.

benchbar share status --json

{"schema_version":1,"cli_version":"…","protocol":3,"bench":"/path/to/bench","site":"mysite.localhost",
"share_site":"share.localhost","state":"on","phase":null,"web_up":true,"degraded":false,"error":null,
"label":"Your Mac","port":8443,"web_port":8001,"lan_ip":"192.168.1.20","started":"…","deadline":"…",
"seconds_left":3600,"can_extend_s":28800,"copy":{…},"allowed_users":["priya@example.com"],"seats":2,
"people":1,"devices_total":1,"devices_online":1,"pending":0,"locked":false,"lock_reason":null,
"budget_left":10,"join_trouble":false,"wipe_failed":0,"lan_guard":"installed","preflight":null,
"setup_interrupted":false}
  • state: on, off, expired or error.
  • lock_reason: host, budget (10 wrong codes; only share code --new opens it), full, or null.
  • wipe_failed: a sign-out that is owed or failed. While sharing is off it reads 1 or more from the marker share stop leaves when it could not end every session of the copy. It reads 1 for a moment after every share remove, until the removed seat’s sessions are gone.
  • pending is always 0: there are no join requests to approve in rooms.
  • lan_guard: as lan-guard status’s state.
  • preflight: null, or with --preflight the critical checks as in share preflight.
  • setup_interrupted: a setup stopped halfway (no share.json, but the one it set aside or the copy is there); share setup --refresh finishes it.

benchbar share preflight --json

{"schema_version":1,"cli_version":"…","protocol":3,"ok":bool,"lan_ip":"…"|null,"checks":[{"id","class","status","message","fix_action"}]}. class is static or critical; status is ok, fail, warn or skip. fix_action is a machine name for the app’s button (none, install_network_protection, allow_node_firewall, open_local_network_settings, rerun_setup, restart_sharing, …).

The room documents

They share bench, share_site and wipe. wipe is null when nothing was owed, else {"retried":bool,"wiped":N|null,"wipe_failed":M|null}.

CommandFields
share codecode ("NNNNNN", a placeholder here), new, budget_left
share inviteurl (benchbar://share/join?v=1&r=…&h=…&s=…&c=…&a=…&x=…, holds the code), text (the message, lines apart by \n), expires_at (ISO 8601, UTC), room
share lock, share unlock (done)locked, lock_reason
share peoplestate (on/off), people: [{id, name, model, ip, seat_id, seat_full_name, online, joined, last_seen}]
share remove (done)device, name, removed, new_code (a bool, never the code)
share assign (done)device, name, seat_id, seat_full_name
share logentries: [{ts, device, user, method, path, status}], truncated
share open-asuser, page, opened: never the link or the session id, even with --print-url
share teardown (done)copy_dropped, archived_path, state_removed

benchbar lan-guard status --json

{"schema_version":1,"cli_version":"…","state":"installed","active":true,
"ports":"8000:8099 9000:9099 11000:11099 13000:13099 3306","anchor":"com.apple/250.benchbar","lan_ip":"192.168.1.20"}
  • state: installed, missing or outdated (the anchor’s rules differ, or the daemon does not load it).
  • active: whether pf refuses the bench ports, by the probe alone (the files are state): true when no bench port answered from lan_ip and the control port did, false when a bench port answered, null with no LAN address or when the probe could not run.

lan-guard install and remove end in a done line with the same fields; allow-node’s carries node, the realpath it allowed.

Port management

benchbar ports plan --json -- PATH ... is read-only. Canonical paths are sorted and deduplicated. The response has schema_version: 1, an opaque token, can_apply (boolean), and entries. Each entry includes path, name, site, mode (automatic or fixed), current and proposed port objects (web, socketio, redis_queue, redis_cache), conflicts (strings), blocked (string or null), service_installed (boolean), and setup_plan (string, or null when setup is blocked): the adoption dry-run output for the proposed allocation, including service and hosts changes. The approval token covers this plan.

ports plan without --json renders a readable preview. ports setup -- PATH ... shows that preview and asks before applying, without manual token copying. ports setup --dry-run only previews. Plan, setup and apply use each bench’s detected site/profile and reject --site or --profile overrides.

ports apply TOKEN --yes -- PATH ... recomputes the selection under the CLI lock; a changed token or any blocked entry fails before adoption. It emits human progress, including completed paths and any failing path, and exits nonzero on failure. Earlier completed entries remain configured. A new preview is required before retrying. With BENCHBAR_SUDO=gui it asks for the /etc/hosts lines of all benches in one macOS password dialog, as adopt does for one (see the privileged steps). Apply does not start services. Socket availability cannot be reserved against unrelated programs; start checks again before launching.

ports check --json --bench-dir PATH returns schema_version: 1, conflicts (strings), mode, and already_running (boolean, positively owned running processes). Clients may treat up as idempotent when already_running is true; restart still needs a conflict check. It checks configured reservations and all listening PIDs, ignoring only listeners positively identified as belonging to that bench.

ports mode automatic|fixed --bench-dir PATH saves the policy and reserves the current ports without moving them. --dry-run does not save it. New benches default to automatic. Fixed mode means the current allocation stays pinned until the policy changes or an explicit CLI --port-offset override is requested.

Windows shim

benchbar.exe runs on Windows and forwards to the CLI in the WSL distro. Its own JSON is not the CLI’s: the setup and report commands are answered by the shim itself. The full contract, with the step ids, is in windows/shim/README.md.

  • benchbar.exe setup check --json prints one document: schema_version, distro, ready, reboot_pending and steps. Each step has id, status (ok, missing, warn or fail), title, detail, action (the setup run action that fixes it, or null), needs_admin and blocking. It is read only.
  • benchbar.exe setup run ACTION --jsonl prints JSON lines: step and log events, then one done line. In the done line changed is a boolean (the action changed something), not the CLI’s changed[] list. The line also has exit, reboot_required, cancelled, warnings and next_actions, and error_id when the action failed with a stable id (distro_running: the action must stop the running distro, and nothing was changed).
  • benchbar.exe report-windows --json prints one line: schema_version, zip, included, skipped (what was left out, and why) and issue_url.
  • benchbar.exe self-update --check --json prints one document and exits 0 whenever it printed: schema_version, current (this benchbar.exe), latest (the newest published release with a Windows zip for this PC, or null), update_available (a boolean, false when latest is unknown), install (installer, store or other), exe, install_dir, arch, release_url, latest_source (api, or release_page when GitHub’s API was rate limited), command (benchbar.exe self-update, or null), notes, error (why latest is unknown, or null), and the CLI’s side: cli_distro, cli (the CLI’s own self-update --check --json document, asked only when the distro already runs) and cli_error (why cli is null). It changes nothing and never starts a distro.