homectl

A unified home automation CLI with first-class support for TP-Link Kasa devices, LG TVs, and the existing color-wheel workflow.

Current commands:

• db - initialize, migrate, inspect, and back up the household SQLite database
• house - add and list houses
• space - add, list, and tree-view rooms/closets/zones
• item - add items and track placement history
• report - summarize a space and the items currently in it
• task - define task templates and selector-driven blueprints
• bulb - one-shot control for bulbs
• sync - RTMP/video-driven ambient lighting sync
• wheel - interactive terminal color picker
• plug - smart plug control
• lgtv - LG WebOS control

Installation

cargo install --path .
# Installs `homectl` into ~/.cargo/bin

# Or build it locally:
cargo build --release
# Binary is at target/release/homectl

This repository is a Cargo workspace with the installable root package homectl, the app entrypoint in apps/homectl/src/main.rs, and shared libraries under crates/.

Household database planning docs live in docs/household-db-plan.md and docs/household-v1.sql. Hands-on walkthroughs live in TUTORIAL.md.

Household workflows

The new household commands use SQLite as the operational source of truth. By default, homectl uses homectl.db in the current directory; override that with --db /path/to/file.db.

Bootstrap a house model

homectl --db home.db db init
homectl --db home.db house add main-home --name "Main Home" --timezone America/Los_Angeles
homectl --db home.db space add living --house main-home --name "Living Room" --kind room
homectl --db home.db space add hall-closet --house main-home --name "Hall Closet" --kind closet
homectl --db home.db space tree --house main-home

Track items and placement history

homectl --db home.db item add monstera-1 --house main-home --name "Large Monstera" --kind plant
homectl --db home.db item place monstera-1 --space living --reason initial-setup
homectl --db home.db item move monstera-1 --to hall-closet --reason frost-warning
homectl --db home.db item show monstera-1
homectl --db home.db item history monstera-1
homectl --db home.db report space living

Define chore building blocks

homectl --db home.db task template add water-plant --title "Water plant" --group chores --emoji plant
homectl --db home.db task blueprint add all-plants --template water-plant \
  --selector '{"tag":"plant","status":"active"}' \
  --expand per-item
homectl --db home.db task template list
homectl --db home.db task blueprint list

These commands intentionally cover the first delivery slice from docs/household-db-plan.md: database lifecycle, houses, spaces, items, placement history, and task scaffolding. Scenes, policies, task scheduling, and floorplan rendering remain planned follow-on work.

Usage

1. Set Mode (One-Shot Control)

Set one or multiple bulbs to a specific state. You can mix global defaults with specific overrides.

Syntax: homectl bulb [OPTIONS] TARGETS...

Where TARGET is IP or IP:KEY=VALUE,KEY=VALUE...

Supported Keys:

• h or hue: 0-360 (Color)
• s or sat: 0-100 (Richness)
• v or val or bri: 0-100 (Brightness)
• on: Turn bulb on
• off: Turn bulb off

Examples:

Turn all bulbs red:

homectl bulb --hue 0 --sat 100 --val 100 192.168.1.50 192.168.1.51

Turn one green and one blue:

homectl bulb 192.168.1.50:h=120,s=100,v=100 192.168.1.51:h=240,s=100,v=100

Set a default brightness but override color for specific bulbs:

homectl bulb --val 50 192.168.1.50:h=0 192.168.1.51:h=120

Turn off one bulb and dim another:

homectl bulb 192.168.1.50:off 192.168.1.51:v=10

2. Sync Mode (Ambient Lighting)

Syncs bulbs to an audio/video stream. Requires ffmpeg installed.

Syntax: homectl sync [OPTIONS] --bulbs IP:SCALE ...

Example:

homectl sync \
  --source rtmp://localhost/live/stream \
  --mode ambient \
  --bulbs 192.168.1.50:1.0 192.168.1.51:0.5

Scene color knobs

The sync command now exposes tools to tame how each frame is reduced to a single color:

• By default, sync snapshots each target bulb's current state before playback starts and restores it on exit; use --hold-last-state to leave the synced look active when the command ends.
• --color-mode <average|median|dominant|brightest> chooses the hue/saturation extraction strategy, while brightness is now derived from the whole frame so darker input naturally produces darker bulbs.
• Very dim or weakly saturated pixels are automatically down-weighted for hue selection, which keeps near-black scenes from drifting into stray greens.
• --scene-saturation-boost <0.0-1.0> lifts the computed saturation so dim scenes stay colorful.
• --scene-brightness-floor <0.0-1.0> keeps the light from collapsing to black during very dark shots.
• --scene-dark-threshold <0.0-1.0> tells the analyzer when a frame counts as a "dark scene," while --scene-dark-scale <0.0-1.0> scales the final brightness so those scenes stay moody rather than flickering to green.
• --target-luma <0.0-1.0> is a gentle normalization knob now; it nudges overall brightness without hard-replacing scene value.

---

Understanding HSV vs. Brightness

Smart bulbs generally work in the HSV color model. It's often clearer than RGB for lighting control.

Hue (H) - The "Color"

• Range: 0 to 360 degrees.
• Represents the pigment of the color.
• Examples:
  • 0 = Red
  • 120 = Green
  • 240 = Blue
  • 60 = Yellow
  • 300 = Magenta

Saturation (S) - The "Richness"

• Range: 0 to 100%.
• Represents how "pure" the color is versus how "washed out" (white) it is.
• Examples:
  • 100% = Pure, deep color (e.g., Neon Red).
  • 50% = Pastel color (e.g., Pink).
  • 0% = White/Gray (no color).

Value (V) - The "Brightness"

• Range: 0 to 100%.
• Represents the intensity of the light emitted.
• Also known as: Brightness.
• Note: In this tool, val, bri, and v are synonyms.
• Examples:
  • 100% = Full brightness.
  • 10% = Dim night light.
  • 0% = Off (Black).

Common Scenarios

"I just want to dim the lights" Keep Hue and Saturation as is (or don't specify them if partial updates are supported/defaults used) and reduce Value. homectl bulb 192.168.1.50:v=20

"I want warm white light" Set Hue to Orange/Yellow (~30-40), Saturation to a low value (~10-20), and Value to taste. homectl bulb 192.168.1.50:h=35,s=15,v=80

"I want pure white" Set Saturation to 0. Hue doesn't matter (usually). homectl bulb 192.168.1.50:s=0,v=100