# CLI Reference

> Complete reference for the broadcast.sh command line tool, covering service control, upgrades, backups, diagnostics, health reporting, and configuration commands for your Broadcast server.

Source: https://sendbroadcast.net/docs/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:

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

Note

All commands must run as **root** (or with `sudo`). The script checks this and exits otherwise. These commands apply to automatic installations only. If you installed manually with Docker, see [Manual Installation](https://sendbroadcast.net/docs/manual-installation).

## Command Summary

| Command | What it does |
|---|---|
| `install` | Install Broadcast onto a fresh Ubuntu server |
| `start` / `stop` / `restart` | Control the Broadcast services |
| `update` | Update the management scripts themselves |
| `upgrade [version]` | Upgrade Broadcast to the latest (or a specific) version |
| `downgrade ` | Roll back to a specific version | | `backup_database` | Create a database backup | | `restore  [--yes]` | Restore a database backup | | `logs ` | Stream live logs for `app`, `job`, or `db` | | `diagnose` | Collect a support diagnostic bundle | | `fix` | Repair installation drift automatically | | `health` | Report server health to the dashboard (runs via cron) | | `monitor-enable` / `monitor-disable` | Turn health reporting on or off | | `monitor` | Write host metrics for the in-app dashboard (runs via cron) | | `trigger` | Process pending triggers from the app (runs via cron) | | `validate_license` | Re-validate your license key | | `change_installation_domain` | Change the server's primary domain | | `generate_encryption_keys` | Generate Active Record encryption keys | | `two_factor ` | Recover from a two-factor authentication lock-out | | `help` | Show usage for all commands | ## Service Control ### start, stop, restart
```bash
./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
```bash
./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](https://sendbroadcast.net/docs/customizing-docker-services). ### upgrade
```bash
# 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.

Warning

Always create a backup before upgrading. See [Backup & Recovery](https://sendbroadcast.net/docs/backup) for the full pre-upgrade checklist, and [Upgrading](https://sendbroadcast.net/docs/upgrading) for what to expect during an upgrade.

 ### downgrade
```bash
./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
```bash
./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
```bash
./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](https://sendbroadcast.net/docs/backup) for the full restore walkthrough, including migrating between servers. ## Logs and Diagnostics ### logs
```bash
./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](https://sendbroadcast.net/docs/monitoring-and-logs). ### diagnose
```bash
./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
```bash
./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. One check deserves a mention because its symptom is silent. The app and job containers run as uid 1000 inside the image, and the directories they write (`app/storage`, `app/uploads`, `app/triggers`, `ssl`) must belong to that uid on the host. On servers where uid 1000 was already taken when Broadcast was installed, typically by `ubuntu` on cloud images, the `broadcast` user got a different uid and those directories ended up unwritable by the container: the dashboard's Upgrade button wrote no trigger file and sat on "Upgrade in Progress" forever, uploads failed, and Thruster could not store its TLS certificate. `fix` (and every upgrade run from the command line) re-owns those directories to uid 1000, looking inside them rather than just at them, and reports `FAIL:` if the change does not take. `app/monitor` is deliberately left to the `broadcast` user, because the host's monitor cron writes it and the container only reads it. A side effect worth knowing: whichever host user already holds uid 1000 gains write access to uploads and triggers. That user almost always has sudo anyway, so this changes nothing in practice. To check a server by hand:
```bash
stat -c %u /opt/broadcast/app/triggers   # 1000 means healthy
```

 ## 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
```bash
./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
```bash
./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
```bash
./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
```bash
./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
```bash
./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](https://sendbroadcast.net/docs/license) for more on licensing. ### change_installation_domain
```bash
./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](https://sendbroadcast.net/docs/domain-names). ### generate_encryption_keys
```bash
./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. ### two_factor
```bash
./broadcast.sh two_factor reset admin@example.com
./broadcast.sh two_factor disable_enforcement
./broadcast.sh two_factor status
```

 Recovery for two-factor authentication when the dashboard cannot help. Users normally manage their own second factor from their profile, and an administrator can reset another user's from **Users**, so reach for this only when nobody who could do that can sign in. - `reset ` clears the user's authenticator and recovery codes. They sign in with their password alone and can enrol again from their profile. - `disable_enforcement` switches off **Require two-factor authentication for all users** (Application → Security). Users who already enrolled keep it. - `status` prints whether two-factor is required and which users have it enabled, with how many recovery codes each has left. Each subcommand runs inside the app container, so Broadcast must be running. See [Two-Factor Authentication](https://sendbroadcast.net/docs/two-factor-authentication) for the full picture. ## Getting Help
```bash
./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.