Skip to content

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 --json

site 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.

FlagWhat it does
--bundle NAMEInstall the apps of a bundle (minimal, common, extended)
--apps "a b"Install these apps, which must be in apps/ already
--dry-runPrint the plan, change nothing
-y, --yesDo not ask; ADMIN_PASSWORD must be set
--jsonJSON 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 --yes

site 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 v16two

site hosts

benchbar site hosts

Adds 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 hosts

site 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 v16dev
benchbar site open-as status --json

site 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.

FlagWhat it does
--with-filesAlso back up the uploaded files (public and private)
--jsonPrint the new backup as JSON (schema); the progress goes to stderr
--dry-runPrint 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-files

site 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 --json

site 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] | --yes

Restores 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.

FlagWhat it does
--from STAMP|PATHThe backup set
--from-site SITEThe site a stamp belongs to (needed with --new)
--newCreate TARGET first
--with-filesRestore the public and private files too (the set must have them)
--no-migrateStop after the restore and the key, before bench migrate
--before-migrate SCRIPTRun 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, --jsonThe plan, with its token
--apply TOKENRun 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 --json
benchbar site restore acme.localhost --from 20260902_090000 --with-files --apply TOKEN --yes
benchbar site restore copy.localhost --from 20260902_090000 --from-site acme.localhost --new --yes

site 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-site repeating the site name exactly;
  • the default site, unless --new-default OTHER names the site that takes its place (it is made the default first, like site 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.

FlagWhat it does
--confirm-site NAMEThe site name again; nothing is dropped without it
--new-default OTHERFor the default site: the site that becomes the default
--dry-runPrint the plan, change nothing (with --json: the steps)
--jsonThe 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-run
benchbar site drop bbtest.localhost --confirm-site bbtest.localhost

To 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).