Command Reference

Command Reference

Complete reference for all lightsctl.sh commands.

Basic Usage

./lightsctl.sh <command> [arguments]

All commands can also be run via Makefile shortcuts: make <command>

Deploying Code Changes

lightsctl.sh is for operating the Pi. To deploy lights-pi source (control server, scripts, fixtures), use the deploy script directly:

bash scripts/deploy.sh

This rsyncs control-server/, scripts/, and lightsctl.sh to the Pi and restarts lighting-control.service. Hard-refresh your browser afterward to clear the PWA service worker cache.

Core Commands

Command	Description
validate	Pre-flight validation of config and connectivity
doctor	Comprehensive health check with recommendations
health	Quick status check (service, web UI, USB, resources)
test-dmx	Verify ENTTEC USB and DMX output capability
backup	Pull QLC+ config to local storage
restore <file>	Restore QLC+ config from backup

Provisioning

Command	Description
setup-full	Full provisioning: setup then harden (recommended)
setup	Base install (requires WIFI1_SSID/PSK)
harden	Firewall, watchdog, unattended upgrades
add-key [pubkey]	Install SSH public key on Pi
static-ip <ip/prefix> <gw>	Configure static IP address
update	Runs sudo apt update && apt upgrade on the Pi. Does NOT pull lights-pi code — use bash scripts/deploy.sh from your workstation for that.

Service Management

Command	Description
status	systemd status for qlcplus-web.service
restart	Restart qlcplus-web.service
logs	Last 80 lines from service journal
logs-errors	Show only ERROR and WARN lines
tail	Follow service logs live
diagnose	Full diagnostic dump

QLC+ Operations

Command	Description
deploy-workspace <file>	Upload workspace to Pi and restart
pull-workspace [output]	Download current workspace from Pi
list-fixtures	Show installed fixture definitions
install-fixture <file>	Upload custom fixture definition
open-web	Open web UI in default browser

Network & System

Command	Description
wifi-status	Show current SSID and IP address
wifi-add-network <ssid> <pass> [priority]	Add a WiFi network
wifi-test	End-to-end connectivity test
wifi-watchdog-install	Install auto-recovery watchdog
scan	Scan network for Pi devices
ssh	Open interactive shell on Pi
reboot	Reboot the Pi
os-version	Show OS and kernel version

AI Scene Generation

Command	Description
generate-scene <desc> [options]	Generate scene from natural language
list-templates	List available scene templates
generate-from-template <name>	Generate from pre-defined template

Options: --preview, --add-to-workspace, --output <file>, --style <style>, --variations <n>, --mock

Control Server

Command	Description
control-install	Install the control server on the Pi
control-status	Show control server status
control-logs	Show control server logs
control-restart	Restart control server
control-uninstall	Remove control server
env-sync	Push local .env to Pi and restart services

MCP Server (LLM Agent Access)

Command	Description
mcp-install	Install the MCP server on the Pi (Streamable HTTP @ :5001/mcp)
mcp-status	Show MCP server status
mcp-logs	Show MCP server logs
mcp-restart	Restart MCP server
mcp-uninstall	Remove MCP server

See MCP-Server for the full tool/resource reference and client wiring (Claude Desktop, ChatGPT, Cursor).

Fixture Groups

Command	Description
group-list	List all fixture groups
group-create <name> <ids> [desc]	Create a new group
group-delete <name>	Delete a group
group-scene <name> <desc> [opts]	Generate scene for a group
group-template <name> <template>	Apply template to a group
group-import	Import groups from QLC+ workspace
group-export [--deploy]	Export groups to workspace