site
The sites of a bench. The guide is Benches and sites. Every command takes the options for every command.
site list
benchbar site list [--json] [--bench-dir DIR]Every site of the bench; the default one, the site benchup waits for,
is marked. benchbar site alone does the same. With --json: each
site’s name, whether it is the default, whether /etc/hosts has it, its
ping code, its db_name and its db_port (never the password)
(schema).
Exit codes: 0; 1 when no bench is found.
benchbar site list --jsonsite add
benchbar site add NAME [--bundle NAME | --apps "a b"] [--dry-run] [--yes] [--json]bench new-site on the bench’s MariaDB with the root password from the
Keychain, the site’s /etc/hosts line, and optionally apps that are
already in apps/. The default site stays as it is. It asks for the new
site’s Administrator password, or reads ADMIN_PASSWORD.
| Flag | What it does |
|---|---|
--bundle NAME | Install the apps of a bundle (minimal, common, extended) |
--apps "a b" | Install these apps, which must be in apps/ already |
--dry-run | Print the plan, change nothing |
-y, --yes | Do not ask; ADMIN_PASSWORD must be set |
--json | JSON lines ending in a done with the site and the default site (the done fields) |
With BENCHBAR_NONINTERACTIVE=1 (or --for-agent) it asks for nothing.
It first names every missing input in one error: ADMIN_PASSWORD,
MARIADB_ROOT_PASSWORD when benchbar has none stored, and --yes.
Exit codes: 0 the site exists; 1 a step failed or an app is not in
apps/, or ADMIN_PASSWORD is missing; 2 the MariaDB root password is
unknown (pass MARIADB_ROOT_PASSWORD).
ADMIN_PASSWORD='...' benchbar site add v16two --bundle minimal --yessite default
benchbar site default NAME [--json]Makes NAME the default site: bench use, the runner’s ping, benchup and
the app all follow it. The processes keep running. With --json it
prints JSON lines ending in a done.
Exit codes: 0; 1 when the site does not exist or bench use fails.
benchbar site default v16twosite hosts
benchbar site hostsAdds a 127.0.0.1 line to /etc/hosts for every site that has none,
inside benchbar’s markers, with one sudo prompt.
Exit codes: 0; 1 when the hosts file could not be written.
benchbar site hostssite open-as
benchbar site open-as on|off|status [NAME] [--yes] [--json]Turns password-less sign in (benchbar open --as USER) on or off for a
site, or shows it. NAME defaults to the bench’s default site. It is off for
every site until you turn it on, also for a site you add or pull later.
The choice is benchbar’s own state for the bench; the site is not changed.
on must be run in a terminal by a person. It prints what a sign in does
(the apps’ on_login and on_session_creation hooks run: last_login,
an Activity Log entry, a mail to System Managers for Administrator, an
ERPNext Customer or Supplier for a Website User, and Frappe may end that
user’s oldest session) and asks first; --yes skips the question.
It is refused when BENCHBAR_NONINTERACTIVE=1 is set, which --for-agent
and benchbar mcp do, and when there is no terminal on stdin, even with
--yes (the BenchBar app turns it on after its own alert). It still records the choice for a site that is not in
developer_mode or not the site the web process answers as, and says that
open --as will refuse it until that changes. off is always allowed; it does not end the sessions already made.
status --json prints one document with open_as_enabled,
developer_mode and open_as; on and off with --json print JSON
lines ending in a done.
Exit codes: 0; 1 when the site does not exist, on is run without a person
at a terminal, or the question is answered no.
benchbar site open-as on v16devbenchbar site open-as status --jsonsite backup
benchbar site backup NAME [--with-files] [--json] [--dry-run]Runs bench’s own bench --site NAME backup and reports the new backup:
the database dump, the site config and, with --with-files, the public
and private files. The backup lands where bench always puts it,
sites/NAME/private/backups/, inside the bench: copy it elsewhere when
it has to outlive the bench. When the bench is stopped, its Redis is
started for the backup and stopped again.
| Flag | What it does |
|---|---|
--with-files | Also back up the uploaded files (public and private) |
--json | Print the new backup as JSON (schema); the progress goes to stderr |
--dry-run | Print the command, change nothing |
Exit codes: 0 the backup exists; 1 the site does not exist or the backup failed.
benchbar site backup macdev --with-filessite backups
benchbar site backups NAME [--json]Every backup of the site, newest first: when it was taken, its size, whether it has the files, and the database file. Read only. The files that share a timestamp are one backup.
Exit codes: 0; 1 when the site does not exist.
benchbar site backups macdev --jsonsite restore
benchbar site restore TARGET --from STAMP|PATH [--from-site SITE] [--new] [--no-migrate] [--before-migrate SCRIPT] [--with-files] --dry-run [--json] | --apply TOKEN --yes [--json] | --yesRestores a backup set that site backup (bench) made into a site of this
bench. TARGET is a site that is there, which is backed up with its files
first, or, with --new, a site that is created first (bench new-site,
with the MariaDB root password benchbar holds and a generated
Administrator password, or ADMIN_PASSWORD; the restore brings the
Administrator password of the backup). The encryption_key of the set is
carried into the target, so stored passwords decrypt. After the restore
come the --before-migrate script, bench migrate and the cache; the
run ends with a check that the site answers list-apps and that the
default site is where it was. The default site never moves, and a
restored site is not muted: it is the same site, not a copy of
production.
--from is a stamp from benchbar site backups (of --from-site, else of
TARGET), the path of a set’s database file (its other files are found
next to it), or a folder (the newest set in it). Encrypted sets are not
taken: benchbar pull --from-dir DIR --as NAME decrypts one.
Run --dry-run --json first: it prints the plan, what it touches, the
backup it takes first and a token. --apply TOKEN --yes then runs exactly
that plan without a question, and refuses it when the sites, the default
site, the hook or the set changed meanwhile
(schema).
A plain --yes from a terminal shows the plan and runs it.
| Flag | What it does |
|---|---|
--from STAMP|PATH | The backup set |
--from-site SITE | The site a stamp belongs to (needed with --new) |
--new | Create TARGET first |
--with-files | Restore the public and private files too (the set must have them) |
--no-migrate | Stop after the restore and the key, before bench migrate |
--before-migrate SCRIPT | Run the executable SCRIPT after the restore, before migrate, in the bench folder, with BENCHBAR_SITE, BENCHBAR_BENCH and BENCHBAR_DB_NAME. Variables named like a secret are removed from its environment. A failing script stops the run before migrate |
--dry-run, --json | The plan, with its token |
--apply TOKEN | Run the reviewed plan (needs --yes) |
Exit codes: 0 restored and verified; 1 a refusal or a failed step (the
output names the backup taken first, to put back); 2 the MariaDB root
password is unknown (pass MARIADB_ROOT_PASSWORD).
benchbar site restore acme.localhost --from 20260902_090000 --with-files --dry-run --jsonbenchbar site restore acme.localhost --from 20260902_090000 --with-files --apply TOKEN --yesbenchbar site restore copy.localhost --from 20260902_090000 --from-site acme.localhost --new --yessite drop
benchbar site drop NAME --confirm-site NAME [--new-default OTHER] [--dry-run] [--json]Removes a site for good. Its database and database user are dropped,
and only the backup taken first can bring the data back; the site’s
address stops working. Check that it is the site you mean and run with
--dry-run first.
It runs bench drop-site, which takes a backup with files first, drops
the database and user, and moves the site folder, with that backup, to
archived/sites/ in the bench (nothing is deleted there). The
MariaDB root password comes from the Keychain and reaches bench on
stdin, never on the command line. Afterwards the site’s 127.0.0.1 line
is removed from /etc/hosts, with one sudo prompt, when it is inside
benchbar’s block and no other bench has a site with that name.
benchbar refuses:
- without
--confirm-siterepeating the site name exactly; - the default site, unless
--new-default OTHERnames the site that takes its place (it is made the default first, likesite default); - the only site of the bench;
- when the backup fails: bench stops before it drops anything, and the site stays.
A hosts line outside benchbar’s block is left alone, and so is the line
when there is no terminal to ask for the sudo password (the app): the
output says which command removes it by hand.
| Flag | What it does |
|---|---|
--confirm-site NAME | The site name again; nothing is dropped without it |
--new-default OTHER | For the default site: the site that becomes the default |
--dry-run | Print the plan, change nothing (with --json: the steps) |
--json | The result as JSON: the backup, the archived folder, the hosts line (schema) |
Exit codes: 0 the site is dropped; 1 a refusal or a failed step; 2 the
MariaDB root password is unknown (pass MARIADB_ROOT_PASSWORD).
benchbar site drop bbtest.localhost --confirm-site bbtest.localhost --dry-runbenchbar site drop bbtest.localhost --confirm-site bbtest.localhostTo bring a dropped site back, restore its backup from
archived/sites/NAME/private/backups/ into a new site with
bench --site NAME restore PATH --with-public-files ... --with-private-files ....
The restore does not bring back the site’s encryption_key: copy it
from archived/sites/NAME/site_config.json into the new site’s
site_config.json, or its stored passwords do not decrypt (see
Troubleshooting).