Skip to content

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.

FlagWhat it does
--printPrint the same contents to the terminal instead
--jsonWrite 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 --print

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

FlagWhat it does
--checkOnly compare with the latest release
--jsonThe 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-runThe plan and the command, nothing runs
--yesDo not ask

Exit codes: 0; 1 when GitHub could not be reached or the question was answered no.

benchbar self-update --check

where

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.

FlagWhat it does
--jsonThe same as JSON, the where schema

Exit codes: 0; 1 for another argument.

benchbar where

docs

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.

FlagWhat it does
--printPrint the URL instead of opening it

Exit codes: 0; 1 for an unknown topic.

benchbar docs doctor

—version

benchbar --version

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

console

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 macdev

db

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 macdev

open

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/todo
benchbar open --site two.localhost --as Administrator --print-url

users

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 priya
benchbar users --json --limit 200

autostart

benchbar autostart on|off

Whether 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 off

mariadb-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-password

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

FlagWhat it does
--allEvery bench with a benchbar agent, after one question; not with --bench-dir
--yesDo not ask. Required without a terminal: a run with no terminal and no --yes is refused
--dry-runShow 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-bench
benchbar uninstall-service --all

To remove BenchBar itself, see Uninstall.

commands

Experiments that are off are left out: see labs.

benchbar commands --json

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

help and version

benchbar --help
benchbar COMMAND --help
benchbar --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.