The openbrowse command

Installing the openbrowse package puts a single command on your PATH. It is the same command whether OpenBrowse came from PyPI or from a git checkout, and it works from any working directory, because nothing about it depends on where you happen to be standing.

openbrowse --help
openbrowse --version

With no subcommand it prints the help and points at openbrowse start, which is what most people want.

The subcommands

Every one of them exits non-zero on failure, so they compose in a script.

Running the server

openbrowse serve runs in the foreground and is what the systemd unit itself invokes. It takes the bind address and port from your configuration unless you override them:

openbrowse serve --host 127.0.0.1 --port 9000

--port 0 means an ephemeral port, and is honoured as such rather than being read as "no port given".

openbrowse start is the one to reach for on a machine that should keep running it. It needs root to write the unit and enable it, so it asks for your password, and it says in plain words whether OpenBrowse will now come back on boot. Where systemd is absent it says so and falls back to running in the foreground.

The service is covered in full under running it as a service, including what happens when you already have a unit of your own.

Updates

openbrowse check-update
openbrowse update

check-update reports the installed version against the latest on PyPI and exits non-zero only if the check itself failed, so "already up to date" is a success. update runs the upgrade through whichever manager owns this copy, uv tool upgrade, pipx upgrade, pip inside its virtual environment or a git pull, and then tells you to restart; unlike the dashboard's button, it does not restart the server for you. Where the owning manager cannot be reached it names the install method and declines rather than running something that would fail. Updating has the full table.

The dashboard does the same two things without a shell: a badge in the navigation when a release is waiting, and a one-click Install and restart on the Settings page that is refused while any session is running. Updating covers both paths and the one thing to do afterwards.

Tuning the host

openbrowse tune --share most --dry-run
openbrowse tune --share most

--share takes all, most or shared, matching the three presets the setup screen and the Settings page offer, and --dry-run prints the plan without touching anything. The command runs a script bundled inside the package and needs root, so it asks for your password on a host where you are not already root, rather than failing with a traceback.

What it actually writes, and why a Raspberry Pi needs it, is under sizing it for your machine. Run it again after every upgrade: the sudoers grant it writes names the script by its full path, and that path moves with the package.

Removing it

openbrowse uninstall

It prints exactly what it is about to remove and then asks you to type uninstall before it does anything: the systemd unit and its capacity drop-in, the tuning sudoers grant, the psi=1 boot flag if one was added, your data directory including .env and your profiles, the downloaded browser, and finally the package. --keep-data and --keep-browser spare the last two of those, and --yes skips the prompt for a scripted teardown.

A source checkout is left where it is. Removing a clone is rm -rf on a directory you chose, and guessing at that is not a thing an uninstaller should do.

Where it reads and writes

Every subcommand resolves one home directory holding .env and data/: ~/.openbrowse for an installed copy, the repository root for a checkout, and whatever OPENBROWSE_HOME names if it is set. Where OpenBrowse keeps its files has the detail, including why OPENBROWSE_HOME is the one variable that cannot live in .env.

There is no walk up from the working directory looking for a .env to read, which matters now that the command runs from anywhere: an unrelated project's file can never end up supplying this server's keys.