CLI reference - supply-drop-bbs

Complete reference for every subcommand and flag.

Synopsis

supply-drop-bbs [OPTIONS] [SUBCOMMAND]

Omitting the subcommand is the same as supply-drop-bbs run.

---

Global options

These options are accepted by every subcommand.

Flag	Env override	Default	Description
--config <PATH>	-	see below	Path to the TOML config file
--data-dir <PATH>	SUPPLY_DROP__BBS__DATA_DIR	<config data_dir>	Override the data directory (database, logs, backups)
--log-level <LEVEL>	SUPPLY_DROP__LOGGING__LEVEL	INFO	Log verbosity: TRACE DEBUG INFO WARN ERROR
--version	-	-	Print version and exit
--help / -h	-	-	Print help and exit

Config file search order

When --config is not given the BBS looks for a config file in this order, stopping at the first one found:

1. ./config.toml
2. /etc/supply-drop-bbs/config.toml
3. ~/.config/supply-drop-bbs/config.toml

If none exists, compiled-in defaults are used. An empty or missing config file is always valid.

--data-dir behaviour

Setting --data-dir clears any database path, log file path, and backup directory that were set in the config file - they are re-derived under the new data directory. If you need an explicit database path alongside a different data directory, set both data_dir and database.path in the TOML file instead.

---

Subcommands

run

supply-drop-bbs run [OPTIONS]

Start the BBS. This is the default when no subcommand is given - the following two commands are equivalent:

supply-drop-bbs
supply-drop-bbs run

What it does:

1. Loads and resolves configuration
2. Initialises tracing / logging
3. Creates the data directory if it does not exist
4. Opens (and migrates) the SQLite database
5. Constructs the BBS host
6. Starts compiled-in transport plugins (mesh, CLI, web admin)
7. Blocks until Ctrl-C or SIGTERM
8. Stops plugins in reverse order and exits cleanly

Examples:

# Systemd service - normal production invocation
supply-drop-bbs run --config /etc/supply-drop-bbs/config.toml

# Development - verbose logging, local data directory
supply-drop-bbs run --data-dir ./dev-data --log-level debug

# Override log level via environment
SUPPLY_DROP__LOGGING__LEVEL=trace supply-drop-bbs run

---

setup

supply-drop-bbs setup [OPTIONS]

Run the interactive first-run setup wizard. Detects your radio device, asks configuration questions, and writes a config.toml. Safe to run on an existing installation - answers are pre-populated from the current config.

The wizard asks:

1. Radio connection type — USB serial or Pi HAT
2. Serial port (USB only) — auto-detected; you confirm or enter manually
3. Radio parameters (USB serial only) — choose a named region preset or enter custom values (frequency, bandwidth, spreading factor, coding rate, TX power); stored in [plugins.mesh.radio] and applied to the device; can be re-applied later with node set-radio
4. BBS name — shown to users on connect
5. Data directory — defaults to /var/lib/supply-drop-bbs
6. Web admin UI — whether to enable it, bind address, and backup directory

After the wizard completes, restart the service to apply:

sudo systemctl restart supply-drop-bbs

Example:

sudo supply-drop-bbs setup --config /etc/supply-drop-bbs/config.toml

---

config check

supply-drop-bbs config check [OPTIONS]

Validate the config file and exit. Exit code 0 means the config is valid; non-zero means it is not.

supply-drop-bbs config check
# config OK

supply-drop-bbs config check --config /etc/supply-drop-bbs/config.toml
# config OK

Use this before restarting the service after an edit:

supply-drop-bbs config check && sudo systemctl restart supply-drop-bbs

---

config show

supply-drop-bbs config show [OPTIONS]

Print the effective configuration as TOML - compiled-in defaults, config file values, and environment overrides all merged and displayed together. Useful for verifying that overrides are applied correctly.

supply-drop-bbs config show
supply-drop-bbs config show --config /etc/supply-drop-bbs/config.toml
SUPPLY_DROP__BBS__DATA_DIR=/tmp/test supply-drop-bbs config show

config require-verify

supply-drop-bbs config require-verify <on|off> [OPTIONS]

Enable or disable sysop verification for new registrations. Writes require_verify to the [bbs] section of the config file. Takes effect on the next BBS restart.

Argument	Meaning
on	New accounts must be verified by an aide or sysop before they can access rooms (default)
off	New accounts are treated as User immediately — no verification step required (SHTF mode)

# Disable verification for emergency / SHTF deployments
sudo supply-drop-bbs config require-verify off \
  --config /etc/supply-drop-bbs/config.toml

# Restore normal verification
sudo supply-drop-bbs config require-verify on \
  --config /etc/supply-drop-bbs/config.toml

Tip: Use the in-BBS sysop command OPENACCESS / CLOSEACCESS instead if you need the change to take effect immediately without a restart.

---

config guest-room

supply-drop-bbs config guest-room <name|off> [OPTIONS]

Set or clear the guest room. Writes (or removes) guest_room in the [bbs] section of the config file. Takes effect on the next BBS restart.

When a guest room is configured, unverified users are placed in that room after registration and can only read and post there. All other rooms and mail are invisible until a sysop verifies them. The room is created automatically on startup if it does not already exist.

Argument	Meaning
<name>	Room name to use as the guest room (e.g. Guests)
off	Disable the guest room feature

# Set a guest room
sudo supply-drop-bbs config guest-room Guests \
  --config /etc/supply-drop-bbs/config.toml

# Disable
sudo supply-drop-bbs config guest-room off \
  --config /etc/supply-drop-bbs/config.toml

Tip: Use the in-BBS sysop command GUESTROOM <name> / GUESTROOM OFF for an immediate live change without a restart.

---

migrate

supply-drop-bbs migrate [OPTIONS]

Apply any pending database migrations and exit. The run subcommand always migrates on startup, so this is only needed if you want to migrate without starting the BBS (e.g. as a pre-flight step in a deployment script).

exit 0   migrations applied (or already up to date)
exit 1   database could not be opened or a migration failed

Example deployment sequence:

supply-drop-bbs migrate --config /etc/supply-drop-bbs/config.toml
supply-drop-bbs run    --config /etc/supply-drop-bbs/config.toml

---

backup

supply-drop-bbs backup [OPTIONS]

Trigger an immediate database backup (VACUUM INTO) and exit. The backup lands in <data_dir>/backups/ (or the configured [backup] directory) with a timestamp filename. The running BBS service does not need to be stopped — VACUUM INTO is non-blocking and consistent.

On success, prints the filename, size in bytes, and destination directory:

Backup created: backup_20260511_142301.db
  size:     2097152 bytes
  location: /var/lib/supply-drop-bbs/backups

---

node show-key

supply-drop-bbs node show-key [OPTIONS]

Connect to the MeshCore companion device via USB serial, perform the handshake, and print the node's 32-byte public key as a 64-character hex string. This is the key other mesh nodes use to contact your BBS.

The BBS service must not be running on the same serial port when you run this.

supply-drop-bbs node show-key
# ab12cd34ef56...  (64 hex chars)

supply-drop-bbs node show-key --port /dev/ttyACM0

Flag	Description
--port <PATH>	Serial port (e.g. /dev/ttyACM0, COM3). Defaults to the port in config.toml.
--baud <N>	Baud rate. Defaults to config.toml value or 115200.

---

node export-key

supply-drop-bbs node export-key [OPTIONS]

Export the companion device's 32-byte private key as a 64-character hex string. Back up this value before a firmware flash or hardware migration — it is the only way to restore your node's mesh identity.

Keep the output secret. Anyone with the private key can impersonate your node.

The BBS service must not be running on the same serial port.

supply-drop-bbs node export-key
# 7f3a1b... (64 hex chars — keep secret)

---

node import-key

supply-drop-bbs node import-key <KEY> [OPTIONS]

Import a 64-character hex key into the companion device as its new private key. The device's mesh identity changes immediately. The corresponding public key (shown by node show-key) will change to match.

Use this to:

• Restore a backed-up key after a firmware flash
• Migrate an identity from one device to another
• Set a specific node key when deploying pre-provisioned hardware

Argument	Description
<KEY>	64 hex characters (32 bytes). Must be valid hexadecimal.

supply-drop-bbs node import-key ab12cd34ef56...
# key imported — node identity updated

Exit codes: 0 on success; 1 if the key is invalid, the port cannot be opened, or the device does not confirm the import.

Web admin: The same operation is available in the Settings page → Node identity → click the ✏️ icon next to the public key.

---

node set-radio

supply-drop-bbs node set-radio [OPTIONS]

Push radio parameters (frequency, bandwidth, spreading factor, coding rate, TX power) to the companion device over USB serial. The device persists these settings in its own flash; you only need to run this command when you want to change them.

The BBS service must not be running on the same serial port when you run this command.

Flag	Description
--preset <NAME>	Named region preset (e.g. "USA/Canada"). Overrides config.toml preset.
--frequency-hz <N>	Carrier frequency in Hz. Overrides preset.
--bandwidth-hz <N>	Channel bandwidth in Hz. Overrides preset.
--spreading-factor <N>	LoRa spreading factor 7–12. Overrides preset.
--coding-rate <N>	Coding rate denominator 5–8. Overrides preset.
--tx-power-dbm <N>	Transmit power in dBm. Overrides preset.
--save	Write the resolved parameters back to config.toml.
--list-presets	Print all available preset names and exit (does not open the port).
--port <PATH>	Serial port (e.g. /dev/ttyACM0, COM3). Defaults to the port in config.toml.
--baud <N>	Baud rate. Defaults to config.toml value or 115200.

Examples:

# List available region presets
supply-drop-bbs node set-radio --list-presets

# Apply the preset stored in config.toml (no flags needed)
supply-drop-bbs node set-radio \
  --config /etc/supply-drop-bbs/config.toml

# Apply a specific preset and save it to config.toml
supply-drop-bbs node set-radio --preset "USA/Canada" --save \
  --config /etc/supply-drop-bbs/config.toml

# Apply fully custom parameters without using a preset
supply-drop-bbs node set-radio \
  --frequency-hz 910525000 --bandwidth-hz 62500 \
  --spreading-factor 7 --coding-rate 5 --tx-power-dbm 20 \
  --save --config /etc/supply-drop-bbs/config.toml

Exit codes: 0 on success; 1 if a parameter is out of range, the port cannot be opened, or the device does not confirm the command.

Config reference: Radio parameters are stored in [plugins.mesh.radio] in config.toml. Saving them there allows node set-radio (with no flags) to re-apply the same settings after a firmware flash.

---

user promote

supply-drop-bbs user promote <USERNAME> [OPTIONS]

Promote a user account to Sysop (permission level 100). The BBS service does not need to be restarted - the change takes effect the next time the user logs in or issues a command.

Argument	Description
<USERNAME>	BBS username to promote (case-sensitive)

supply-drop-bbs user promote alice
# alice promoted to sysop (level 100)

sudo supply-drop-bbs user promote alice \
  --config /etc/supply-drop-bbs/config.toml

Exit codes: 0 on success; 1 if the user is not found or the database cannot be opened.

Aide level: There is currently no --aide flag. To promote to Aide (level 50) instead of Sysop, use the in-BBS .EU <username> command as a Sysop, or update the database directly:

sudo sqlite3 /var/lib/supply-drop-bbs/bbs.sqlite \
  "UPDATE users SET permission_level = 50 WHERE username = 'alice';"

---

user demote

supply-drop-bbs user demote <USERNAME> [OPTIONS]

Demote a user account back to User (permission level 10). Removes Sysop or Aide privileges. The change takes effect the next time the user issues a command.

Argument	Description
<USERNAME>	BBS username to demote (case-sensitive)

supply-drop-bbs user demote alice
# alice demoted to user (level 10)

Exit codes: 0 on success; 1 if the user is not found or the database cannot be opened.

---

user set-password

supply-drop-bbs user set-password <USERNAME> [OPTIONS]

Reset a user's password without requiring the old password. Prompts for the new password interactively (input is hidden) and asks for confirmation. The BBS service does not need to be stopped.

Argument	Description
<USERNAME>	BBS username whose password will be reset (case-sensitive)

sudo supply-drop-bbs user set-password alice \
  --config /etc/supply-drop-bbs/config.toml
# New password for alice: ••••••••
# Confirm password:       ••••••••
# password reset for alice

The new password must be at least 6 characters. The same operation is available in the web admin UI — open the user's detail drawer on the Users page and click reset password (sysop-only; requires the BBS to be running).

Exit codes: 0 on success; 1 if the user is not found, the password is too short, or the database cannot be opened.

---

Permission levels

Level	Value	How to set
Unvalidated	0	Assigned on registration; cannot log into BBS features until validated
User	10	user demote or in-BBS .EU
Aide	50	In-BBS .EU as Sysop, or direct DB update
Sysop	100	user promote or in-BBS .EU as Sysop

The first account registered on a fresh installation is automatically promoted to Sysop.

---

Common workflows

Bootstrap a new installation

# First user self-promotes to Sysop automatically on registration.
# If you need to promote a second sysop:
sudo supply-drop-bbs user promote alice \
  --config /etc/supply-drop-bbs/config.toml

Recover lost sysop access

sudo systemctl stop supply-drop-bbs
sudo supply-drop-bbs user promote alice \
  --config /etc/supply-drop-bbs/config.toml
sudo systemctl start supply-drop-bbs

Reset a user's password

If the BBS is running and you are logged into the web admin as a sysop, open the Users page, click the username to open the detail drawer, and use the reset password form.

If the web UI is unavailable, use the CLI (the BBS does not need to be stopped):

sudo supply-drop-bbs user set-password alice \
  --config /etc/supply-drop-bbs/config.toml

Verify config before restarting

supply-drop-bbs config check --config /etc/supply-drop-bbs/config.toml \
  && sudo systemctl restart supply-drop-bbs

Run a local dev instance

cargo build
mkdir -p dev-data
./target/debug/supply-drop-bbs run \
  --config dev-config.toml \
  --data-dir dev-data \
  --log-level debug