CLI reference

boat <command> [subcommand] [flags] [arguments]

Run boat help for a summary. In a terminal, running boat with no arguments, or an incomplete command such as boat model, opens an interactive command picker. Outside a terminal, plain boat prints the service status.

Flags go before positional arguments, for example boat log --follow backend.

Service

`start`

boat start

Starts BOAT and prints its status. On first run it creates safe defaults if boat setup has never been run: the web app on 127.0.0.1:7234, no models, and user-systemd autostart on Linux when available.

`stop`

boat stop

Stops the gateway, backend and all model workers.

`restart`

boat restart

Stops and starts BOAT, for example after editing configuration by hand.

`status`

boat status [--json]

Shows whether BOAT is running, its address and the service details.

Flag	Description
`--json`	Machine-readable output

`open`

boat open

Opens the web app in your default browser.

`service`

boat service enable
boat service disable

Turns starting at login and after reboot on or off. Linux uses a user systemd unit; macOS uses the fallback supervisor.

Configuration

`setup`

boat setup [--non-interactive] [flags]

Configures Core: network binding, ports, upload limit, Default Device, autostart and release channel. Without --non-interactive it opens a guided terminal UI. Setup validates the result, checks that ports are free, applies a changed Default Device to installed models and restarts BOAT if it was running. It never installs models.

Flag	Default	Description
`--non-interactive`		Apply flags without the UI
`--bind <addr>`	`127.0.0.1`	Listen address for the web app
`--port <n>`	`7234`	Web app port
`--backend-port <n>`	`7236`	Internal backend port
`--upload-limit <size>`	`1g`	Maximum upload size
`--default-device <d>`	`auto`	`auto`, `cpu`, `mps` or `cuda:<n>`
`--autostart=<bool>`	`true` on Linux	Start at login
`--channel <name>`	`stable`	`stable` or `beta` updates
`--accept-insecure-lan`		Required for a non-loopback `--bind`

See Configuration for details.

`config`

boat config show
boat config validate

show prints config.toml. validate checks the configuration and device settings and prints Configuration is valid. on success.

Models

<model> is <id> or <id>:<tag>. See Installing and managing models.

`model install`

boat model install <model> [--tag <tag>] [--accept-license]

Installs the latest compatible version from the official registry, validates it with a real inference and enables it. Pass a folder path such as ./model-packages/my-model to install a local package.

Flag	Description
`--tag <tag>`	Same as `<id>:<tag>`
`--accept-license`	Accept the model's license terms without a prompt

boat model install sam3-litetext
boat model install locate-anything:3b-Q8_0

`model update`

boat model update <model> [--tag <tag>] [--accept-license]

Installs and validates the newest compatible version, switches to it and deletes the previous one. Keeps the enabled/disabled state and the original install date. If anything fails, the old version stays active.

`model remove`

boat model remove <model>

Stops the worker and deletes the package code, environment, weights and install record. Weight caches no other install uses are deleted too; files you provided yourself are not.

`model disable`

boat model disable <model>

Blocks new inference and stops the running worker, keeping all files.

`model enable`

boat model enable <model>

Checks that files and environment are intact and makes the model available again. It loads on first use.

`model list`

boat model list [--json]

Lists installed models without using the network: model:tag, first install date, enabled state, version, effective device and idle time. JSON output splits id and tag.

`model setup`

boat model setup [<model>]
boat model setup <model> --non-interactive [--device <d>] [--idle-seconds <n>]
boat model setup recover

Sets the device and idle unload time for one installed tag. Without --non-interactive it opens a terminal UI.

Flag	Description
`--device <d>`	`auto`, `cpu`, `mps`, `cuda:<n>`, or `default` to inherit the Default Device
`--idle-seconds <n>`	Seconds a loaded worker stays resident; `0` unloads after each request
`recover`	Resume an interrupted runtime or device switch

Users and workspaces

These commands work while BOAT is stopped. User IDs and owner filters are case-sensitive.

`user list`

boat user list [--json]

`user create`

boat user create <user-id> [--password-stdin]

Creates an account. The password is prompted for, hidden, and confirmed. With --password-stdin it is read from standard input instead.

`user set-password`

boat user set-password <user-id> [--password-stdin]

Resets a password. This is how password recovery works, since BOAT does not use email.

`user delete`

boat user delete <user-id> [--yes]

`workspace list`

boat workspace list [--owner <user-id>] [--type personal|team] [--json]

Logs and diagnostics

`log`

boat log [--follow] [all|gateway|backend|model]

Prints service logs. The component defaults to all: gateway is the supervisor, backend the API server and model the model workers.

Flag	Description
`--follow`	Keep streaming new lines

`log recent`

boat log recent [--level error|warning|info|all] [--limit <n>] [--json]

Structured application logs from the database, newest first. Defaults to --level error and --limit 50 (1–1000).

`doctor`

boat doctor [--fix] [--json] [--report]

Checks the platform, configuration, service manager, accelerator selection, runtime profile and eligible GPUs.

Flag	Description
`--fix`	Recreate missing secrets and reinstall the autostart unit if enabled
`--json`	Machine-readable results, including the active runtime profile and GPU UUIDs
`--report`	Also save the results to `doctor-report.json` in the state directory

Data

`backup create`

boat backup create

Creates a coordinated backup of BOAT's data and prints the archive path.

`backup list`

boat backup list

`backup restore`

boat backup restore --yes <archive>

Replaces current data with the backup. Requires --yes.

Releases

`update`

boat update [--check]

Updates BOAT on the configured channel. It backs up first, validates the new version by starting it once and restores the previous version automatically on failure. --check only reports whether an update exists.

`rollback`

boat rollback --yes

Restores the backup taken before the last update and discards newer data.

`uninstall`

boat uninstall [--purge-data --yes --confirm-purge=DELETE]

Removes the BOAT runtime and autostart unit. Data is preserved unless you pass all three purge flags, which delete the data, state, cache and config directories.

`version`

boat version

Prints the version and commit. boat --version and boat -v work too.

Development

`dev backend`

boat dev backend

Runs the source backend with hot reload, using the same configuration and isolated data as boat setup. Only meaningful in a source checkout after source ./dev_activate.sh.

Environment variables

Variable	Effect
`BOAT_HOME`	Keep config, data, state and cache under one directory
`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`	Override the default XDG locations
`BOAT_VERSION`, `BOAT_CHANNEL`, `BOAT_INSTALL_DIR`	Installer options; see Installation