# The openbrowse command (/docs/cli) 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. ```bash openbrowse --help openbrowse --version ``` With no subcommand it prints the help and points at `openbrowse start`, which is what most people want. ## The subcommands [#the-subcommands] | Command | What it does | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | `start` | Registers OpenBrowse as a systemd service, then enables and starts it, so it is running now and again after every reboot | | `stop` | Stops the service. `--disable` also stops it starting on boot | | `restart` | Restarts the service | | `status` | Shows `systemctl status` for the service | | `serve` | Runs the server in the foreground until you interrupt it | | `version` | Prints the installed version | | `check-update` | Asks PyPI whether a newer release exists and says so | | `update` | Installs the newer release, if there is one | | `tune` | Sizes the host for OpenBrowse. Linux only, and needs root | | `uninstall` | Removes everything OpenBrowse put on this machine, then the package itself | Every one of them exits non-zero on failure, so they compose in a script. ## Running the server [#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: ```bash 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](/docs/installation#run-it-as-a-service), including what happens when you already have a unit of your own. ## Updates [#updates] ```bash 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](/docs/installation#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](/docs/installation#updating) covers both paths and the one thing to do afterwards. ## Tuning the host [#tuning-the-host] ```bash 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](/docs/installation#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 [#removing-it] ```bash 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. Your data directory holds the profile cookie jars, which are live credentials for every site those profiles are logged into, and they are not recoverable once removed. Pass `--keep-data` if you intend to reinstall. ## Where it reads and writes [#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](/docs/installation#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.