CLI reference

The workspace produces one binary, theme-agent.

Commands

Command	Behavior
`daemon [--log-level L] [--config PATH]`	Run the headless daemon in the foreground.
`status [--json]`	Read current daemon state.
`set <light\|dark\|system\|sun\|auto>`	Change the running mode without persisting the default.
`subscribe [--json]`	Stream daemon events until interrupted.
`config path`	Print the active platform configuration path.
`config show [--json]`	Print parsed configuration.
`config set mode <mode>`	Persist the default mode and reload a reachable daemon.
`config set fallback <light\|dark>`	Persist the fallback and reload.
`config set location <lat> <lon>`	Persist coordinates and reload.
`service <install\|update\|uninstall\|start\|stop\|restart\|status>`	Manage user-level daemon and tray entries.
`tray`	Run the native tray process; available with the default `tray` feature.

config set ... edits TOML and live-reloads a running daemon. See Configuration for the schema and validation rules.

Output contracts

Human output is intended for interactive terminals. For integrations, use status --json, config show --json, subscribe --json, or the local NDJSON protocol. Those JSON representations are the machine-facing contract.

CLI failures use structured project errors. When a command requested JSON, failures are formatted as JSON rather than mixed with human prose.

User service lifecycle

theme-agent service install
theme-agent service status
theme-agent service restart
theme-agent service update
theme-agent service stop
theme-agent service start
theme-agent service uninstall

install and update register the current binary, preserve configuration, enable startup at login, and start the user-level service without root or administrator access. With the tray feature, installation manages both daemon and tray login entries; uninstall removes both entries but does not delete user configuration.

Tray feature and behavior

The optional Cargo feature tray is enabled by default. A --no-default-features build contains the headless daemon and CLI but has no tray command or tray autostart entry.

The tray runs as a separate thin IPC client. Its GUI main thread owns the event loop while worker tasks communicate with the daemon. Start it directly with:

theme-agent tray

The menu:

displays the current effective theme;
selects Light, Dark, System, Sun, or Auto mode;
opens config.toml in the default application, creating it if absent;
requests an explicit configuration reload;
quits only the tray, leaving the daemon running.

The tray follows live subscription events. If no daemon is available, it attempts to start the managed service or spawn a detached daemon before connecting.