Documentation

Command Reference

Complete reference for all lightsctl.sh commands.

Basic Usage

bash

./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

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

Was this page helpful?