Teams: profiles, lockfile and pull
Three tools keep a team’s benches alike. A team profile is the recipe for
a new bench. The lockfile pins the exact commits every bench should run.
benchbar pull brings a copy of a production site into a local one.
Team profiles
A team profile is your organisation’s bench recipe: a small TOML file
that names a built in base profile and your apps with their repos and
branches. It lives outside BenchBar, in
~/.config/benchbar/profiles/NAME.toml, in a team config repo you
subscribed to, or in a clone
listed in BENCHBAR_PROFILE_PATH.
base = "v15-lts" # Python, Node and MariaDB come from heresite = "acme.localhost"scheduler = false
[[apps]]name = "erpnext"repo = "https://github.com/frappe/erpnext"branch = "version-15"
[[apps]]name = "acme"repo = "git@github.com:acme/acme.git"branch = "main"benchbar profile create acme --from-bench ~/frappe-bench # write one from a bench you havebenchbar profile list # built in and team profilesbenchbar profile show acmebenchbar install --profile acme # a new Mac, the same bench~/frappe-bench is an example: use your bench’s folder. profile create only reads the bench.
The file is a strict subset of TOML (strings, booleans, integers and one line lists; no escapes, no inline tables), and a repo URL with a user name or token is refused, since the file is meant to be committed. Every key is listed in Configuration.
A built in profile of the same name wins. The BenchBar window’s Team Profiles page lists them too.
Sharing a profile
A profile that works on your Mac often does not work on a teammate’s:
it names your SSH alias (git@github-work:...), the feature branch you
happen to be on, or a repo in your personal GitHub account. Export
writes a copy that is safe to hand over, import and subscribe bring it
in on the other side, and check says up front which repos a teammate
cannot read.

Sending one
benchbar profile export acme --plan # read only: the review, nothing writtenbenchbar profile export acme --out ~/acme.toml # review, confirm, writebenchbar profile export acme --branch acme_ecr=main --drop scratch_app --out ~/acme.tomlThe review lists each app with its access, its branch before and after, and what it requires:
- Repo URLs lose any user info, and an SSH alias becomes the real host
(
ssh -Greads it from your~/.ssh/config). - Each app follows its repo’s default branch, read with your own
credentials (through your SSH alias, if the repo uses one). An app on
the base’s release branch (erpnext, hrms or india_compliance on
version-15) keeps it, since their default branch needs another Frappe.--branch APP=BRpicks another one. accessispublicwhen git can read the repo without any credentials,privateotherwise,personalwhen it is private and its GitHub owner is a person rather than an organisation (teammates must be added to it one by one),unknownwhen offline.requirescomes from each app’shooks.pyin the bench (--bench-dir), unless the profile already says it. Dropping an app that a kept app requires is refused.
Commit the file to your team’s config repo, or send it.
In the app, a profile’s ⋯ menu on Team Profiles has Export… with the same review:

Receiving one
benchbar profile import ~/Downloads/acme.tomlbenchbar profile import https://github.com/acme/bench-config/blob/main/acme.toml --planbenchbar profile check acme # which repos can you read?benchbar install --profile acmeImport takes a local file or an https URL (a GitHub file or gist page is
fetched raw), 64 KB at most, and writes
~/.config/benchbar/profiles/NAME.toml with its source, only after it
parses. A file of the same name is diffed and replaced only when you
confirm. A profile names the repos install clones, and their code runs
in your bench, so import only from people you trust and read the app
list in the plan (--plan shows it without writing anything). check asks git, with your own keys and tokens and never a
prompt, whether each repo and branch can be read. install --profile
does the same and leaves out the apps it cannot clone, and every app that
requires one, and lists them in its plan and at the end.
benchbar profile update acme fetches the source again, shows the diff
and asks. benchbar profile remove acme moves an imported file to
~/.config/benchbar/removed/. For a profile that came from a
subscription, it moves the whole subscription aside, with every profile
in it. It never removes a file you wrote yourself.
In the app, Import… on Team Profiles takes a file or a link and shows the same check before anything is written:

Subscribing to a team’s config repo
benchbar profile subscribe git@github.com:acme/bench-config.gitbenchbar profile list # its profiles, and how far behind the clone isbenchbar profile update --all # fetch, show the diff, ask, fast forwardbenchbar profile remove acme-bench-config # unsubscribe (moved aside, not deleted)Subscribe clones the repo into
~/.config/benchbar/sources/OWNER-REPO/. Its profiles are the *.toml
files in its profiles/ folder, or at its root when it has none; nothing
else in it is read or run. Subscriptions come after your own folder and
before BENCHBAR_PROFILE_PATH, in the order you subscribed; profile list warns when a name is hidden by an earlier file. Nothing updates on
its own. When the bench’s team profile comes from a subscription that is
behind, doctor warns
(profile_outdated) as of the
last fetch; benchbar doctor --fetch checks the remote first.
Every flag is in the profile reference.
The team lockfile
A team profile is the recipe; benchbar.toml is the exact state, so
every developer’s bench runs the same commits. Keep it in your main
custom app and commit it there:
benchbar lock write --lock apps/acme/benchbar.toml # once; the path is rememberedbenchbar lock check # read only, exit 1 on any differencebenchbar lock apply --dry-run # what a teammate's bench would changebenchbar lock applylock apply clones missing apps, switches clean apps to the locked
branch and fast forwards to pinned commits, then runs requirements and
build. It never touches a site (it prints the site add, app install
and migrate steps instead) and never overwrites local work: an app with
local changes or commits of its own is skipped with a warning. Doctor
reports drift as a warning (lock_drift).
The file pins each app’s repo, branch and, optionally, commit, in the
order of sites/apps.txt, plus the sites and the apps each one has:
schema = 1[bench]profile = "v15-lts"frappe_bench = "5.31.0"[[app]]name = "erpnext"repo = "https://github.com/frappe/erpnext"branch = "version-15"commit = "b5f784612d5b7969b72848dda5b22f10d3a8f764"[[site]]name = "acme.localhost"default = trueapps = ["erpnext", "acme"]benchbar finds the file from --lock PATH, then BENCHBAR_LOCK, then the
path remembered for the bench, then <bench>/benchbar.toml. A bench is
rarely a git repo itself, which is why the file usually lives in your
custom app.
A copy of production
benchbar pull prod:erp.example.com --as erpcopy --dry-run # read only, prints the planbenchbar pull prod:erp.example.com --as erpcopy # asks before it restoresbenchbar pull --from-dir ~/Downloads/erp-backup --as erpcopy # a Frappe Cloud downloadprod is a Host from ~/.ssh/config. Pull takes the latest backup that
already exists on the server, so nothing is written there (--new-backup
runs bench backup first, which also deletes older backups on the server,
so it asks you to type the site name). The download resumes when the link
drops. The copy goes into a new local site, which pull creates
(bench new-site) as a step of its plan: pull refuses a site name
that exists. --replace overwrites that site’s database and files
instead, after backing it up and asking again. A name that cannot be
restored into (a folder in sites/ that is no site) stops the check,
--dry-run included. --no-migrate stops after the restore, and
--before-migrate SCRIPT runs a script of yours between the two. The copy gets the
production encryption_key so stored passwords still decrypt, has email muted and the scheduler paused before it
ever starts, and runs bench migrate when your apps are newer. When the
bench lacks an app production has, pull stops and prints the
bench get-app command; --skip-app APP restores without it. Encrypted
backups are decrypted locally with gpg (brew install gnupg).
The encryption key and the passwords never appear on a command line, in
the output or in the log. The download is kept in
<bench>/.benchbar/pulls/ after a failed run, so the next run resumes;
a successful run removes it unless you pass --keep-staging.
Every flag is in the pull reference. When passwords do not decrypt after a restore by hand, see Troubleshooting.