report and other commands
Every command takes the options for every command.
report
benchbar report [--print | --json]Writes a redacted diagnostics zip, ~/Desktop/benchbar-report-<stamp>.zip,
for a bug report. It holds doctor and status as JSON, the versions of
everything involved, the launchd agent, Procfile.lean, state.json and
the last 200 lines of bench.log and worker.error.log.
Site config files are never copied, only their key names. Any value
whose key looks like a password, secret, token, key, API or auth
credential is replaced by ***, and so is anything shaped like a secret
whatever its key: user:password@ in a URL (a redis URL, a git URL with
a token), JWTs, GitHub, Slack, OpenAI and AWS tokens. Email addresses
become <email>. Your home folder, user name and every name of the Mac
are replaced by placeholders. REDACTIONS.txt inside the zip lists what
was replaced. benchbar logs --json (and the MCP log tool) applies the
same rules.
| Flag | What it does |
|---|---|
--print | Print the same contents to the terminal instead |
--json | Write the zip and print {"zip": path, "redactions": n}, the report schema the app reads |
Exit codes: 0; 1 when the zip could not be written.
benchbar report --printAttach the zip to an issue at https://github.com/askysh/benchbar/issues.
self-update
benchbar self-update [--check] [--json] [--dry-run] [--yes]Updates the benchbar CLI and the BenchBar app with the one line
installer (the app’s Update Now ran the same command up to 0.7.0; since
0.7.1 it asks Sparkle). With BenchBar.app installed, benchbar hands
off to the app’s CLI, so the app’s case below applies. For release 0.7.2:
curl -fsSL https://raw.githubusercontent.com/askysh/benchbar/v0.7.2/install.sh | bash -s -- --yes --version v0.7.2.
It asks the GitHub API for the latest release, shows this CLI’s and the
app’s versions and the command, and asks before it runs. The installer
comes from that release’s tag and installs that release, even if a newer
one is published while you read the prompt. It changes no
bench and never runs bench update.
A CLI that is a git checkout of your own (not ~/.local/share/benchbar)
gets --app-only and the git -C PATH pull to run; a CLI installed
some other way gets --app-only too. An app in a writable folder other
than ~/Applications is replaced where it is (BENCHBAR_APP_DIR).
A CLI installed with Homebrew is upgraded by Homebrew: the command is
brew upgrade askysh/tap/benchbar, run after the same question, and the
installer never runs. The app is not this command’s then: it updates
itself, or comes from the cask (brew upgrade askysh/tap/benchbar-app), and a note says which.
The CLI inside BenchBar.app (install is app; Homebrew’s and the
installer’s benchbar hand off to it once the app is installed) updates
with the app. For the cask’s app the command is brew upgrade askysh/tap/benchbar-app, run after the same question. Otherwise
nothing runs: open BenchBar and choose Check for Updates, and Sparkle
replaces the app and its CLI. update_available
compares only the CLI. When brew says benchbar is already installed
right after a release, the tap has not caught up yet; try again a few
minutes later.
| Flag | What it does |
|---|---|
--check | Only compare with the latest release |
--json | The same as JSON, never runs anything: current, app_version, app_path, latest, release_url, update_available (true, false, null offline), install (managed, checkout, other, homebrew, app), cli_dir, app_only, app_dir, command, notes, error |
--dry-run | The plan and the command, nothing runs |
--yes | Do not ask |
Exit codes: 0; 1 when GitHub could not be reached or the question was answered no.
benchbar self-update --checkwhere
benchbar where [--json]How this CLI was installed and where its things are: the install kind
(homebrew, managed for the one line installer, app for the CLI
inside BenchBar.app, checkout for a git clone, or other), the
Homebrew or installer CLI it was handed off from, the path it records
for itself in the helper block,
the ~/.local/bin links and every fix command (under Homebrew
<prefix>/opt/benchbar/bin/benchbar, which brew upgrade keeps), its
state folder, and the BenchBar app it finds. Read only; it needs no
bench.
| Flag | What it does |
|---|---|
--json | The same as JSON, the where schema |
Exit codes: 0; 1 for another argument.
benchbar wheredocs
benchbar docs [TOPIC] [--print]Opens this documentation in your browser, or the page of one topic:
install, quick-start, app, sites, apps, doctor, teams,
agents, mcp, cli, config, json, runners, troubleshooting,
decisions, roadmap or contributing. benchbar docs --help lists
every topic with its aliases.
| Flag | What it does |
|---|---|
--print | Print the URL instead of opening it |
Exit codes: 0; 1 for an unknown topic.
benchbar docs doctor—version
benchbar --versionThe first line is always benchbar <version>, which the app and scripts
read. When BenchBar.app is installed in ~/Applications or
/Applications, a second line gives the app’s version.
list
benchbar list [--json]Every bench benchbar knows about: path, default site, sites, ports, and
whether its service is installed. It never pings a site. With --json,
the list schema.
Exit codes: 0.
benchbar list --jsonconsole
benchbar console [--site NAME] [--bench-dir DIR]bench --site NAME console in the bench folder: an IPython shell with
frappe connected to the site. Without --site, the bench’s default site.
It replaces the benchbar process, so the terminal is bench’s until you
leave with Ctrl-D. Nothing is written and no lock is taken. While the
bench is stopped, calls that need Redis (frappe.cache, enqueue) fail;
benchbar says so before it starts.
Exit codes: bench’s; 1 when the site does not exist.
benchbar console --site macdevdb
benchbar db [--site NAME] [--bench-dir DIR]bench --site NAME mariadb: the MariaDB shell on the site’s database,
logged in as the site’s own database user from its site_config.json.
The MariaDB root password is not used and nothing is written to disk.
Exit codes: bench’s; 1 when the site does not exist.
benchbar db --site macdevopen
benchbar open [--site NAME] [--as USER] [--path /app/...] [--no-browser] [--print-url] [--json] [--bench-dir DIR]Opens the site in your browser. With --as USER you are signed in as that
user, with no password: the quickest way to check what a role sees and which
workflow actions it gets. Without --site, the bench’s default site;
without --path, /app (or / for a Website User).
--as works only on a site you turned Open as on for
(benchbar site open-as on NAME, in a terminal),
with developer_mode on (its site_config.json, else
common_site_config.json), for Administrator too, only while the bench
runs, and only on the site the web process answers as: bench serve serves
the default_site of common_site_config.json for every name, so on a
bench with one that is the only site you can sign in on
(benchbar site default NAME, then benchrestart, moves it;
site list --json says where it works in open_as, and whether you turned it on in open_as_enabled). Inside WSL the
browser is Windows’, which reads its own hosts file, so --as opens only a
*.localhost name itself; for another name add it to the Windows hosts
file and open the --print-url link. Plain open (no --as) needs the
bench running and a name the browser can reach as well.
--as starts a Frappe session for the user the way
bench browse --user does and opens /login?redirect-to=PATH&sid=…;
frappe sets the cookie and sends the browser on to PATH, so the session id
does not stay in the address bar. It stays in the browser’s history and the
web log, as with bench browse.
What a sign-in does on the site, as a real login would: the user’s
last_login is updated, and every app’s on_login and
on_session_creation hooks run. With Frappe and ERPNext that means:
- an Activity Log entry “USER logged in” for every switch;
- a mail to the System Managers when you sign in as Administrator
(
notify_admin_access_to_system_manager); - for a Website User, ERPNext can create a Customer or a Supplier
(
create_customer_or_supplier, with the Portal Settings default role).
Frappe keeps only the newest sessions of that user (simultaneous_sessions,
2 by default), so an older one (another browser, a test run) can be signed
out. benchbar site open-as off does not end the sessions already made.
IP and login-hour restrictions on the user apply; two-factor login does not.
A site with deny_multiple_sessions on signs that user out everywhere else.
--print-url prints the link instead of opening it (in --json as url);
the link holds the session id, so treat it like a password. --json without
--print-url leaves it out. Nothing is written to disk and no run log is
kept.
Exit codes: 0 opened (or printed); 1 a refusal: no such site or user, a
disabled user, Open as is off for the site, the bench is stopped, the site is not in developer mode, the
site name does not resolve (benchbar site hosts), or Frappe refused the
login.
benchbar open --as priya@example.com --path /app/todobenchbar open --site two.localhost --as Administrator --print-urlusers
benchbar users [--site NAME] [--search TEXT] [--limit N] [--json] [--bench-dir DIR]The enabled users of a site, to pick one for open --as (refused while Open as
is off for the site): System Users
first, most recent login first, with up to five roles each (the automatic
All, Guest and Desk User left out). --search matches the user id or full
name; --limit is 1 to 500 (50 by default), and truncated in --json
says more users matched. Reads only; needs the bench running.
benchbar users --search priyabenchbar users --json --limit 200autostart
benchbar autostart on|offWhether the bench may come back after login, when it was running before. Without an argument it says which it is.
Exit codes: 0; 1 for another argument, or when the agent could not be written.
benchbar autostart offmariadb-password
benchbar mariadb-password [--yes]Prints the MariaDB root password kept in the Keychain (item
benchbar-mariadb; on Linux a 0600 file in the state folder), after
asking. --yes skips the question.
Exit codes: 0 printed; 1 declined, or no password in the Keychain.
benchbar mariadb-passworduninstall-service
benchbar uninstall-service [--bench-dir DIR | --all] [--yes] [--dry-run]Stops the bench (like benchbar down), then removes its launchd agent,
the runner and Procfile.lean, after asking. It also removes the
# >>> benchbar >>> block from your shell rc file, so benchup and the
other helpers are gone for every bench until benchbar repair or
benchbar service on a remaining bench writes the block again. The
bench, its sites, apps and databases are not touched; the plist is moved
to ~/Library/LaunchAgents-disabled/ and the other files are backed up
first. --dry-run shows the steps.
When the folder is no longer a bench (emptied by a cleanup tool, or
deleted) but its agent is still installed, it removes only that agent:
every com.benchbar.* agent whose working directory is the path is
booted out and its plist moved aside. Such an agent otherwise restarts
every 20 seconds, exits with code 127 and fills the log; doctor’s
dead_agents check
points here.
With --all it does the same for every bench that has a benchbar agent
in ~/Library/LaunchAgents, one after the other, after one question
that lists them; a folder that is no bench any more loses only its
agent. Run it before brew uninstall benchbar: Homebrew cannot stop the
agents itself. A bench that fails (launchd keeps its job) does not stop
the others; run it again for what is left.
| Flag | What it does |
|---|---|
--all | Every bench with a benchbar agent, after one question; not with --bench-dir |
--yes | Do not ask. Required without a terminal: a run with no terminal and no --yes is refused |
--dry-run | Show the steps, change nothing |
Exit codes: 0; 1 declined, refused for lack of a terminal, no bench and no agent at the path, or with
--all a bench that could not be uninstalled.
benchbar uninstall-service --bench-dir ~/dev/v16-benchbenchbar uninstall-service --allTo remove BenchBar itself, see Uninstall.
commands
Experiments that are off are left out: see labs.
benchbar commands --jsonEvery command and subcommand as one JSON document: its usage line, a
summary, its flags with a line of help each, its environment variables,
and what it needs. The needs are tty (it may ask a question), sudo
and network. The document also says whether the command changes things
(mutating) and what --json gives (json: document, stream or
none). The same table prints benchbar COMMAND --help. Agents use it
to find out what a command does before they run it.
Exit codes: 0.
benchbar commands --jsonhelp and version
benchbar --helpbenchbar COMMAND --helpbenchbar --version--help (or -h, or benchbar help) prints every command and option.
benchbar COMMAND --help prints the usage, the flags and the needs of
one command (for example benchbar logs --help). --version prints
benchbar and the version.