CLI Reference

Every Broadcast server installed with the automatic installer is managed by a single script: /opt/broadcast/broadcast.sh. It handles service control, upgrades, backups, diagnostics, and configuration changes on the host.

To use it, SSH into your server and run commands as root:

ssh root@your-server
cd /opt/broadcast
./broadcast.sh help

Command Summary

Service Control

start, stop, restart

./broadcast.sh start
./broadcast.sh stop
./broadcast.sh restart

These control the broadcast systemd service, which runs the Docker Compose stack (the web app, the background job worker, and PostgreSQL). A restart stops and recreates the containers; expect a brief interruption while the app boots.

Updates and Versioning

update

./broadcast.sh update

Updates the management scripts only (a git pull in /opt/broadcast). It does not touch the application itself or restart anything. You rarely need to run this directly, since upgrade runs it as its first step.

The update refuses to run while files under /opt/broadcast have local modifications, and names the affected files. If you need to customize the Docker services, use the override file instead of editing Broadcast’s files — see Customizing Docker Services.

upgrade

# Upgrade to the latest version
./broadcast.sh upgrade

# Upgrade to a specific version
./broadcast.sh upgrade 3.5.0

Updates the management scripts, stops the service, pulls the new application image for your architecture (AMD64 or ARM64), and restarts everything. Old Docker images are cleaned up automatically after the upgrade. If any step fails mid-upgrade, the previously installed version is restarted automatically so your site stays up while you investigate.

downgrade

./broadcast.sh downgrade 3.4.2

Rolls the application back to a specific version. The version argument is required. Downgrading is for recovering from a problematic upgrade: your database schema is not rolled back, so only downgrade to a version close to the one you upgraded from, and restore a backup if the schema has moved ahead of the target version.

Backup and Restore

backup_database

./broadcast.sh backup_database

Creates a timestamped, compressed dump of the primary database in /opt/broadcast/db/backups/ and copies it into the app’s storage so it appears on the Application → Backups page. Each backup ships with a version file and a .sha256 checksum. Only the most recent backup file is retained on disk.

restore

./broadcast.sh restore broadcast-backup-20260801.tar.gz

# Skip the confirmation prompt (for scripts and automation)
./broadcast.sh restore broadcast-backup-20260801.tar.gz --yes

Restores a database backup. The process verifies the backup’s checksum (when the .sha256 file is present next to the tarball), stops the application, checks version compatibility, restores the database, runs migrations if the backup came from an older version, and restarts the services.

Restoring a backup created on a newer version than the installed one is blocked; upgrade first, then restore. See Backup & Recovery for the full restore walkthrough, including migrating between servers.

Logs and Diagnostics

logs

./broadcast.sh logs app   # Web application
./broadcast.sh logs job   # Background job worker
./broadcast.sh logs db    # PostgreSQL

Streams live container logs (docker logs --follow). Press Ctrl+C to stop following. Logs are also available in the web interface; see Monitoring and Logs.

diagnose

./broadcast.sh diagnose

Collects a support diagnostic bundle: full container logs, HTTP probes of each layer of the stack (the app server directly, the proxy, and the HTTPS origin), and general system state. Run this before restarting anything when something is wrong, because a restart destroys the container logs that explain what happened. Attach the resulting bundle when contacting support.

fix

./broadcast.sh fix

Repairs installation drift: re-asserts directories, file ownership, permissions, systemd units, cron entries, registry login, log rotation, and required environment settings. In short, everything the installer originally set up. Each check prints ok:, fixed:, or FAIL:, and the command exits non-zero if anything could not be repaired. It is safe to run at any time; it only converges the server back to its intended state.

One-time provisioning (Docker itself, the firewall, swap) is out of scope: a missing prerequisite points you at ./broadcast.sh install instead of risking a partial reinstall.

Health Reporting

Broadcast servers can report their health to your sendbroadcast.net dashboard, so you can be alerted when a server goes down. The down system is an email platform, so it cannot email you about itself.

monitor-enable, monitor-disable

./broadcast.sh monitor-enable
./broadcast.sh monitor-disable

monitor-enable turns health reporting on for this server and checks in immediately. To actually receive alerts, monitoring must also be enabled for the server on the Servers page of your sendbroadcast.net dashboard.

monitor-disable stops all health reporting. It places a flag file at /opt/broadcast/.no_health_reports that silences the reporter entirely before it contacts anything, a switch you can verify yourself if you want zero phone-home behavior.

health

./broadcast.sh health

The reporter itself. It runs automatically from cron every minute; you almost never run it by hand, but doing so is harmless: it probes the local stack and sends a report according to the current reporting state. Until monitoring has been confirmed as enabled, it sends only a minimal handshake (no probes or system details), at most once per hour.

Automated Commands

These run from cron jobs the installer sets up. You generally never run them manually, but they are safe if you do.

monitor

./broadcast.sh monitor

Writes host metrics (CPU load, memory, disk usage) to a JSON file the app reads, powering the system metrics shown in the web interface.

trigger

./broadcast.sh trigger

Processes trigger files the app writes to request host actions: upgrading, updating SSL certificate domains, and creating backups. This is how the Create backup button and in-app upgrades work: the app writes a trigger file, and this cron-driven watcher picks it up on the host.

Configuration

validate_license

./broadcast.sh validate_license

Re-validates your license key against sendbroadcast.net and refreshes the registry credentials used to pull application images. Run this if image pulls start failing with authentication errors, or after your license has been renewed. See Getting a license for more on licensing.

change_installation_domain

./broadcast.sh change_installation_domain

Interactively changes the server’s primary domain. It shows the current domain, prompts for the new one, and after confirmation updates the domain configuration, restarts the services, and provisions a new SSL certificate. Point the new domain’s DNS at the server before running this, or certificate issuance will fail. See Domain Names.

generate_encryption_keys

./broadcast.sh generate_encryption_keys

Generates the Active Record encryption keys in app/.env if they are missing. New installations create these automatically; this command exists for older installations upgrading to a version that requires them. It never overwrites existing keys, and it tells you to restart afterwards for the keys to take effect. fix also runs this check.

Getting Help

./broadcast.sh help

Prints the usage summary for all commands. If a command fails in a way you can’t resolve, run ./broadcast.sh diagnose and send the bundle to support.