CLI Reference

Every beacon command — install, deploy, operate, upgrade — and what each one does.

The Beacon CLI installs and operates a beacon on a host. It creates the deployment directory, generates secrets, checks the host, and wraps Docker Compose behind beacon. It's scoped to host operations; game administration lives in the dashboard (beacon admin).

Install & update the CLI

Install the Beacon CLI

Pick the host you are installing on. The page selects a likely OS automatically; the commands below update when you choose another one.

Install on Linux

curl -fsSL https://beacon-mc.io/install.sh | sh

Pin a CLI release

curl -fsSL https://beacon-mc.io/install.sh | BEACON_CLI_VERSION=0.31.1 sh

Confirm the install

beacon --version

The installer pulls the public cli image, extracts the prebuilt app to the host, and links beacon / beacon.cmd onto your user PATH. Requires Docker and Node.js 20+.

beacon upgrade self-updates the CLI as part of a version upgrade, so you rarely rerun the installer by hand. Overrides for forks/self-hosted Atlas: BEACON_REPO, BEACON_CLI_IMAGE_REPO, BEACON_INSTALL_DIR, BEACON_BIN_DIR.

Commands

Command	Purpose
`beacon`	First-run onboarding wizard if unconfigured; maintenance TUI otherwise
`beacon create [dir] --yes …`	Non-interactively write deployment files (automation)
`beacon doctor`	Check Docker, compose files, required env, and template drift
`beacon up`	Preflight, pull images, start, wait for readiness
`beacon upgrade [version]`	Pick/pin a release, self-update the CLI, refresh templates, pull, recreate changed services
`beacon pull`	Pull pinned release images without restarting
`beacon restart`	Recreate every service so `.env` edits and refreshed templates take effect
`beacon down`	Stop and remove containers
`beacon nuke`	Destroy the stack and its data (preserves Caddy cert state unless `--include-ingress-state`)
`beacon status`	Probe compose state, admin-rpc, web, and Minecraft
`beacon logs [service]`	Print (or stream) stack logs
`beacon open`	Open the beacon web app
`beacon admin`	Open the admin dashboard

Lifecycle commands — beacon up, down, pull, restart, status, and upgrade — act on every registered beacon on the host by default (falling back to ~/.beacon when none are registered). Use --dir <path> to target a specific deployment, or bare beacon to switch between registered deployments in the TUI. beacon upgrade resolves the release once, then applies it to each beacon in turn with a per-beacon health-gated rollback.

Common flags

--yes — skip confirmation prompts (required for non-interactive create).
--dir <path> — operate on a specific deployment directory.
--json — machine-readable output (beacon status --json).
--no-color — plain output for log pipelines.
beacon logs: --follow to stream, --tail <n> for window size, --since <duration> for a time filter (default: last 200 lines, then exit).
beacon up: --no-wait to skip the readiness wait, --wait-timeout <s> to extend it (useful for slow first-world generation).

First deploy

Interactive (recommended) — the six-step wizard probes Docker, then walks Preflight → Mode → Details → Review → Deploy → Done:

beacon

Scripted — for automation and reproducible production:

beacon create --yes \
  --app-url https://mc.<tailnet>.ts.net \
  --tailscale-auth-key tskey-... \
  --mc-image itzg/minecraft-server:java25 \
  --mc-version 26.1.2
beacon doctor
beacon up
beacon status

--mc-image and --mc-version are required explicit inputs. Omit --mc-port to auto-pick from 25565 upward. --mode custom selects custom-domain ingress (add --acme-email); the default is Tailscale.

Upgrade, rollback & pinning

beacon upgrade 0.31.1 --yes     # apply a specific version
beacon upgrade                  # interactive release picker
beacon upgrade 0.31.0 --yes     # roll back (tags are immutable per release)

BEACON_VERSION is always a concrete release — latest is rejected because it hides what's running and breaks update detection. beacon doctor warns on an unpinned install. Full details in Updating Beacon.

What's not in the CLI

Anything that operates on running game state belongs to the dashboard, not the CLI: people, invites, the allowlist, snapshots/schedules, the audit log, Atlas listing, and server settings/mods. Run beacon admin and use the dashboard — it has the typed forms, role checks, and audit attribution the CLI can't provide.

Running over SSH

The TUI needs a real terminal. Over a flaky SSH session, BEACON_TUI=plain beacon drops to a plain menu. In a non-TTY context (CI, piped output), beacon prints help and exits — use beacon create --yes for non-interactive setup.