Command line

browserhive [serve] [flags]            start the server (default command)
browserhive init [flags]               install browsers, choose the default one, create the data dir
browserhive doctor [flags]             diagnose the host and configuration
browserhive purge [flags]              delete local state (inventory, then confirmation)
browserhive config show|schema|validate
browserhive db status|backup|restore <file>|migrate
browserhive admin reset-password
browserhive admin tokens list|create <name>|revoke <name>
browserhive channels list | test <name> | preview <name> [--sample <kind>]
browserhive version | --version | -v
browserhive help [command] | --help | -h

If the first argument is not a command word, serve is assumed and every argument is a flag. Each command accepts only its own flags; passing a server flag to purge is a usage error. --help wins over everything, --version over everything except --help, and -- ends flag parsing.

Help text is generated from the configuration schema, so browserhive --help always lists every server flag with its type, default and environment variable. Flags are camelCase; see Configuration.

serve

Resolves the configuration, opens storage (migrating the database if needed), starts the listener and prints the banner:

 BrowserHive 0.2.0  ·  bun 1.4.2  ·  patchright 1.63.0
 MCP        http://127.0.0.1:9876/mcp            (auth: token)
 Dashboard  http://127.0.0.1:9876/               (admin)
 Data dir   /home/me/.local/share/browserhive     (db v6, 12 MiB, 3 backups)
 Config     env:2  file:/home/me/browserhive.config.json:9  cli:1
 Sessions   cap 8 (derived from 12 GiB RAM) · lease 2h · persistence memory
 Stealth    standard · patchright · humanize on · fingerprint off
 Telemetry  otel → http://127.0.0.1:4318 (http/protobuf)
 Vault      bitwarden (locked)
 Notify     2 channels (1 from startup) · links → https://browserhive.example.net

 config: maxSessions=8 (cli) shadows config-file=4
 Press Ctrl-C to stop.

The Notify row appears once a notification channel or publicUrl is set. The first-run dashboard password and the first agent token are printed once in this banner and never logged. Ctrl-C (or SIGTERM) stops gracefully within --shutdownTimeout: listeners, then sessions (traces are finalized), then storage. A second Ctrl-C exits immediately with code 130.

Output streams: under --transport stdio, stdout carries only MCP frames and everything else goes to stderr. Under HTTP, the banner and pretty logs go to stdout on a terminal, and JSON logs go to stderr, so browserhive 2> logs.jsonl captures them. Colour is on for terminals; NO_COLOR or --color never disables it.

All server flags are in the configuration reference.

Notification channels

--notificationChannel declares a notification channel for this run (startup channels). Repeat it for several channels. It is a flag only: there is no environment variable or config-file key for it.

--notificationChannel "<platform>:<param>=<value>,<param>=<value>…"

A list value joins its items with +; a value cannot contain , (write %2C). Secret parameters are always env:NAME, the name of an environment variable (not starting with BROWSERHIVE_); a secret written into the flag is refused with exit 64, because process arguments are visible to other users of the machine.

Platform	Parameters
telegram	name, token=env:NAME, chat (a chat id), optional thread (a forum topic id)
discord	webhook mode: name, webhook=env:NAME (the webhook URL). Bot mode: name, mode=bot, token=env:NAME (the bot token), channel (the channel id), optional guild (the server id)
ntfy	name, topic (a topic, or env:NAME), optional server (default https://ntfy.sh), token=env:NAME, reply (the reply topic for act buttons, or env:NAME), replyToken=env:NAME
webhook	name, url (a URL, or env:NAME), optional secret=env:NAME (the signing key)

Rules, all optional: categories (needs-you+problems+wrap-ups+reports+system), min (info, warn, error, critical), sessions (session name patterns such as shop-*), harness, content (counts, titles, full), quiet=22:00-07:00, tz=Europe/Berlin (the channel’s time zone, for quiet hours and reports; default BrowserHive’s), digest (daily@09:00, daily:weekdays@09:00 for Monday to Friday, weekly:fri@17:00; the day and time may be left out: daily is every day at 09:00, weekly is Friday at 17:00), anomaly=on with anomaly.errorRate (percent or off), anomaly.minCalls, anomaly.attention (minutes or off), anomaly.blocked (the spike factor or off), anomaly.blockedMin, anomaly.capacity and anomaly.degraded (on/off) (daily digests and anomaly alerts), ttl.<category>=2h (Telegram at most 47h), deleteWhenResolved (true, or a + list of categories), images (a + list of categories; needs content=full), maskImages=true, actButtons=true (answer from your phone; Telegram, Discord bot mode, ntfy with reply, webhook) and allow (a + list of Telegram or Discord user ids allowed to press them; not for ntfy).

init

One-time setup, safe to re-run:

1. Create the data directory (0700) and subdirectories.
2. Install Chromium for Playwright (honours PLAYWRIGHT_BROWSERS_PATH).
3. Install Patchright’s Chromium when stealthDriver is auto or patchright.
4. Report the browsers on this machine (bundled Chromium, installed Google Chrome and Microsoft Edge) and whether each can run inside Chromium’s sandbox; on a terminal, offer the default-browser menu (Enter keeps the current one). See Installation: choosing the browser.
5. Create or migrate the database.
6. Print next steps.

Flag	Meaning
--browsers chromium	Browsers to install (only chromium today; Chrome and Edge channels use the OS installation).
--force	Re-download even if present.
--skipBrowsers	Skip the browser downloads (data directory and database only).
--dataDir <path>, --config <path>	Where state and configuration live.
--stealthDriver <auto|patchright|playwright>	playwright skips the Patchright download.
--writeSchema	Write browserhive.schema.json next to a discovered config file.
--channel <chromium|chrome|edge>	Make this the default browser and save defaultChannel to the config file. Without a terminal it needs --yes.
--installChrome	Install Google Chrome with Google’s installer (playwright install chrome; needs administrator rights).
--yes	Save the --channel choice without asking.

init never asks anything without a terminal, in CI (CI set) or in a container.

doctor

Checks Bun, browsers (the bundled Chromium, installed Chrome and Edge, that the configured defaultChannel is installed, version drift, managed policies that block automation), Chromium’s sandbox for each installed browser (each is launched once), running as root or in a container, data directory permissions and disk space, configuration, port availability, bw when the vault is on, the database and pending migrations, the OTLP endpoint when telemetry is on, maxSessions against RAM, publicUrl (whether it reaches this BrowserHive; see public address), notification channels (each --notificationChannel parses and every variable a channel names is set), and config-file permissions when it holds secrets (not when authTokens only references environment variables). It counts the values that came from references and warns about each referenced variable that was not set, so its default is in use. It also warns when the data directory contains an unrecognised data file, which BrowserHive neither reads nor migrates.

--json prints [{ check, status, detail }]. Exit codes: 0 all good, 2 warnings only, 1 a check failed. When the configured browser cannot run sandboxed, the text output ends with what to do on this machine. --printApparmorProfile prints an AppArmor profile for the configured browser (for Ubuntu 23.10+) and exits; install it yourself with sudo tee /etc/apparmor.d/<name> and sudo apparmor_parser -r.

purge

Deletes local state after showing what will go: row counts per table, directory sizes and absolute paths.

Flag	Meaning
(none)	Delete the database (with its WAL files) and sessions/. You type YES to confirm.
--all	Also delete saved logins, uploads, backups and the admin credentials. Vault bindings and policies are lost with the database. Asks for a second YES.
--dryRun	Print the inventory and exit.
--yes	Skip the prompts. Without a terminal and without --yes, purge refuses.

Stop the server first; purge warns if the database still lists open sessions.

config

Command	Output
config show [--json]	Every key with its effective value, source and shadowed values. Secrets are <redacted>. A value read from an environment variable through a reference shows config-file via $NAME. --json prints { key: { value, source, shadowed, … } }, with refs and template for referenced values.
config schema	The JSON Schema for browserhive.config.json.
config validate [--config <path>]	Runs the full resolver and prints exactly what serve would; exit 64 on error.

db

Command	Meaning
db status	Schema version, oldest compatible reader version, pending migrations, size, last backup, integrity check.
db backup [--out <file>]	Consistent copy of the database (VACUUM INTO).
db restore <file> [--yes]	Replace the database with a backup. Refuses while a server is running, checks the file is a BrowserHive database, and backs up the current file first.
db migrate [--dryRun]	Apply pending migrations (normally done by serve).

See Upgrading.

admin

Command	Meaning
admin reset-password	New seed password for the dashboard, printed once and written to admin/credentials.txt (0600); a change is forced at next login. Refuses while the server is running.
admin tokens list [--json]	Agent bearer tokens: name, public prefix, created, last used.
admin tokens create <name> [--json]	Issue a token. The plaintext is shown only now.
admin tokens revoke <name>	Revoke immediately.

Token commands work on the database directly when the server is stopped, or through the REST API of a running server with --url <server> and an operator credential.

channels

Command	Meaning
channels list [--json]	Every notification channel: platform (with the Discord mode), status (and “from startup”), where it sends, whether its variables are set, whether chat answers reach BrowserHive (connected, reconnecting, offline (reason), or — when act buttons are off), the last delivery and the last 24 hours; under the table, each channel’s next digest in its time zone and its anomaly state.
channels test <name> [--json]	Sends a real test message. Exit 0 when the platform accepted it, 1 with the reason when it did not.
channels preview <name> [--sample <kind>] [--json]	Prints the platform request a send would make (secrets shown as variable names); sends nothing. Samples: attention (default), attention-resolved, vault-confirm, tool-errors, crash, degraded, test, digest, anomaly (the report samples follow the channel’s schedule, zone and content level).

They talk to the running server: --url defaults to the configured host and port, and --token (an operator API token) or --cookie authenticates. See Notifications.

version

browserhive 0.2.0 (bun 1.4.2, sqlite 3.53.2, playwright 1.63.0, patchright 1.63.0)

--json for scripts.

Exit codes

Code	Meaning
0	Success, or clean shutdown after a signal.
1	Fatal runtime error (a boot phase failed after configuration, storage corruption, purge or doctor failure).
2	doctor found warnings only.
3	Policy refusal at startup: INSECURE_BIND_REFUSED, ADMIN_REQUIRES_HTTP, BLOCKLIST_LOAD_FAILED, PORT_IN_USE, DB_NEWER_THAN_BINARY, SANDBOX_UNAVAILABLE (--sandbox on). Printed as [CODE] message.
64	Usage error: unknown flag or key, invalid value, conflicting settings, missing argument.
130	A second interrupt arrived before graceful shutdown finished.