CLI Reference
Global Options
casectl [--host URL] [--version] [-h|--help] COMMAND
| Option | Default | Description |
|---|---|---|
--host |
http://127.0.0.1:8420 |
Daemon API URL (env: CASECTL_HOST) |
--version |
Show version and exit | |
-h, --help |
Show help and exit |
Running casectl with no command shows a status summary (requires the daemon to be running).
casectl doctor
Run local hardware and dependency checks. Does not require the daemon.
casectl doctor
Checks: Python version, smbus2, I2C device, I2C permissions, expansion board probe (0x21), OLED probe (0x3C), CPU temp sysfs, luma.oled, Pillow.
casectl serve
Start the casectl daemon in the foreground.
casectl serve [--bind ADDR] [--port PORT] [--log-level LEVEL]
| Option | Default | Values |
|---|---|---|
--bind |
from config (127.0.0.1) |
Any address. 0.0.0.0 enables LAN access |
--port |
from config (8420) |
Any port |
--log-level |
info |
debug, info, warning, error, critical |
Fan Commands
casectl fan status
Show current fan mode, duty cycle, and RPM per channel.
casectl fan status
casectl fan mode
Set the fan operating mode.
casectl fan mode MODE
| Mode | Description |
|---|---|
follow-temp |
Automatic PWM based on CPU temperature curve |
follow-rpi |
Mirror the Raspberry Pi’s own fan PWM signal |
manual |
Fixed duty cycle (set with fan speed) |
custom |
Reserved for plugin-defined curves |
off |
Fans disabled |
casectl fan mode follow-temp
casectl fan mode off
casectl fan speed
Set fan speed for a specific channel (switches to manual mode).
casectl fan speed CHANNEL DUTY
| Argument | Range | Description |
|---|---|---|
CHANNEL |
0-2 | Fan number |
DUTY |
0-100 | Speed percentage |
casectl fan speed 0 75 # set fan 0 to 75%
casectl fan speed 1 100 # set fan 1 to 100%
LED Commands
casectl led status
Show current LED mode, colour, and health.
casectl led status
casectl led mode
Set the LED operating mode.
casectl led mode MODE
| Mode | Description |
|---|---|
rainbow |
Automatic colour cycling (STM32 firmware) |
breathing |
Pulsing brightness effect (STM32 firmware) |
follow-temp |
Colour follows CPU temperature (cool=blue, hot=red) |
manual |
Fixed colour (set with led color) |
custom |
Reserved for plugin-defined effects |
off |
LEDs disabled |
casectl led mode rainbow
casectl led mode off
casectl led color
Set LED colour and switch to manual mode. Accepts three formats:
casectl led color NAME # named colour
casectl led color '#FF0080' # hex code
casectl led color R G B # R G B values (0-255 each)
casectl led color red
casectl led color arctic-steel
casectl led color '#8AAAC4'
casectl led color 255 0 128
Named colours: red, green, blue, white, yellow, cyan, magenta, orange, pink, purple, teal, coral, gold, lime, navy, arctic-steel
OLED Commands
casectl oled status
Show current screen, rotation, and per-screen enabled state.
casectl oled status
casectl oled screen
Enable or disable a screen in the rotation cycle.
casectl oled screen INDEX --enable|--disable
| Screen | Index | Content |
|---|---|---|
| clock | 0 | Date, large time, weekday |
| metrics | 1 | IP address, CPU/MEM/DISK gauges |
| temperature | 2 | Pi and case temp dial gauges |
| fan_duty | 3 | Pi/C1/C2 fan duty dial gauges |
casectl oled screen 0 --enable
casectl oled screen 3 --disable
casectl oled rotation
Set OLED display rotation.
casectl oled rotation DEGREES
Valid values: 0 or 180.
casectl oled rotation 180
casectl monitor
Show current system metrics from the daemon.
casectl monitor
Displays CPU usage, memory, disk, CPU temp, case temp, IP address, and fan duty/RPM per channel.
Config Commands
casectl config get
View a configuration section.
casectl config get SECTION
Sections: fan, led, oled, service, alerts, mqtt, automation.
casectl config get fan
casectl config set
Set a configuration value. Config stores integer enum values for modes.
casectl config set SECTION KEY VALUE
casectl config set fan mode 0 # follow-temp mode
casectl config set service api_host 0.0.0.0 # enable LAN access
casectl config set oled rotation 180
Service Commands
Manage the casectl systemd service (requires sudo for install/uninstall).
casectl service install # install .service + .timer units, enable auto-start
casectl service uninstall # disable and remove units
casectl service start # start the daemon now
casectl service stop # stop the daemon
casectl service restart # restart the daemon
casectl service status # show systemd status
casectl service logs # show last 50 lines from journald
casectl service logs -f # follow log output (Ctrl-C to stop)
casectl service logs -n 100 # show last 100 lines
casectl top
Interactive terminal dashboard with real-time system stats.
casectl top [--interval SECONDS] [--once]
| Option | Default | Description |
|---|---|---|
--interval, -n |
2.0 |
Refresh interval in seconds (0.5-60) |
--once |
Render a single snapshot and exit (for scripts/CI) |
Displays CPU temperature, fan speed/mode, RGB LED status, memory, disk usage, and daemon health in a live-updating Rich layout.
Interactive keys:
| Key | Action |
|---|---|
m |
Cycle fan mode (follow-temp -> follow-rpi -> manual -> off) |
+ / = |
Increase fan speed by 10% |
- |
Decrease fan speed by 10% |
q |
Quit |
Requires an interactive terminal with at least 60 columns and 15 rows. Use --once for non-interactive environments.
casectl top # interactive dashboard
casectl top -n 0.5 # faster refresh
casectl top --once # single snapshot for scripts
casectl token
Display the current API access token. Only generated when the daemon binds to a non-localhost address.
casectl token