Apps
benchbar app adds, installs and updates the apps of a bench. An app
is a git repository in the bench’s apps/ folder, such as erpnext; a
site is one Frappe instance in the bench, with its own database, and an
app does nothing on a site until it is installed there. benchbar app
uses bench itself (get-app, install-app, migrate, build) and git
only to read an app and to fast forward it. The examples use the site
macdev; benchbar site list shows yours.
benchbar app list # branch, commit, local changes, sitesbenchbar app add crm --site macdev # from config/apps.tsvbenchbar app add git@github.com:acme/acme.git --branch main --all-sitesbenchbar app install crm --site v16two # an app the bench already hasbenchbar app update erpnext --dry-run # the changelog and the planbenchbar app update erpnext # backup, fast forward, migrate, buildAdding an app
app add takes a name from the registry in config/apps.tsv (erpnext,
hrms, payments, crm, helpdesk, lms, wiki, insights, drive, builder, raven)
or any git URL: GitHub, SSH, or a host alias from ~/.ssh/config. The
registry names the branch for each profile.
--branch picks another branch, --name another folder name, and
--site S or --all-sites installs the app right away.
app add checks that git can read the repo before it changes anything,
so a private repo without a key or token fails at once with the fix.
Private repositories work with your SSH key or your gh login. It never
replaces an existing app. A clone that does not finish is moved to the
backups, not left half done.
app add URL --dry-run --json prints the whole plan first, required
apps from hooks.py included, with a token; --apply TOKEN --yes runs
exactly that plan without a question. Coding agents add apps this way
(see Coding agents and MCP).
--commit SHA pins an app to a commit, and several apps can share one
plan and one token: app add A --commit SHA B --install-on s1,s2. The
options belong to the app before them. See
app add.
Installing on a site
app install NAME --site S installs an app the bench already has on one
of its sites.
Updating an app
app update NAME fast forwards one app. It shows the changelog first,
backs up the sites that have the app, then runs requirements, migrate
and build, and restarts the bench when it is running. migrate changes
the sites’ databases and is not undone by moving the app back, so keep
the backup: --skip-backup skips it, which makes sense only for a site
you can rebuild. --dry-run shows the changelog and the plan and
changes nothing.
app update never runs bench update, never rebases and never resets: a
dirty or diverged app is refused.
When a run stops after it changed something, benchbar keeps the steps
that did not finish. The next app update NAME runs those steps and
nothing else, although the app is already at its new commit. Doctor
warns with app_update_pending until then. --discard-pending drops the
record. The same holds for an app add that stopped at a build, an
install or a restart (app_add_pending): run app add again and the new
plan lists what is left. A failed build skips the install, so an app is
never installed on a site whose assets were not built.
Focus apps and their dependencies
You pull the app you work on yourself, so a warning about it is noise. What goes stale quietly are the apps it needs. benchbar calls the apps you work on focus apps, and doctor warns only about the apps they need:
[WARN] Dependencies of focus apps: exponent_custom_v1 (needed by exponent_ecr) is 30 commits / 12 days behind upstream/develop fix: benchbar app update exponent_custom_v1 --bench-dir ~/frappe-benchAn app is a focus app when it has local changes, is on a branch other
than the one the profile names (or the remote’s default branch), or has
a commit by your git config user.email in the last 14 days. What it
needs comes from required_apps in each app’s hooks.py, followed
through other apps, so an app two steps away counts too. Every other app
gets one summary line (apps_behind).
benchbar app focus # every app: focus or not, why, needed by, behindbenchbar app focus exponent_ecr # pin it as a focus appbenchbar app unfocus erpnext # pin it as not one (a branch you only tried)benchbar app focus erpnext --auto # infer againDoctor is read only and never touches the network on its own, so it
stays fast and works offline: the numbers are those of the last fetch,
yours or benchbar’s, and an app never fetched is unknown, never a
failure. benchbar doctor --fetch or benchbar app focus --fetch
fetches the dependencies first; OFFLINE=1 never fetches.
In the app
The BenchBar window’s Apps page does the same: add an app from the
registry or any GitHub URL, install it on a site, and update it after
reading the changelog. Each app shows whether it is a focus app, and a
menu sets it to Auto, Focus or Ignore; Check Remotes fetches the
dependencies (app focus --fetch). See The menu bar app.
Keeping a team on the same apps
A team profile names the apps a new bench gets, and the benchbar.toml
lockfile pins their commits. See Teams.