Skip to content

cli.md

Latest commit

 

History

History
135 lines (100 loc) · 8.72 KB

cli.md

File metadata and controls

135 lines (100 loc) · 8.72 KB
Raw

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 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.1.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 v1, 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)

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

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.

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

version

browserhive 0.1.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.