Configuration

Print the active path instead of assuming it:

theme-agent config path

Typical locations are:

• Linux: ~/.config/theme-agent/config.toml
• macOS: ~/Library/Application Support/theme-agent/config.toml
• Windows: %APPDATA%\theme-agent\config.toml

A missing file uses defaults. Saving through the CLI validates the configuration and creates parent directories.

Complete example

mode = "auto"          # light | dark | system | sun | auto
fallback = "light"     # light | dark

[location]              # optional except for explicit sun mode
latitude = 51.5072
longitude = -0.1276

[sun]
elevation = -0.833      # valid range: -18 through 18

[theme]
light = "catppuccin-latte"
dark = "catppuccin-mocha"

[neovim]
enabled = true

[hooks]
on_light = ["notify-send", "Theme", "light"]
on_dark = ["notify-send", "Theme", "dark"]
on_start = ["theme-apply", "{theme}"]

The CLI directly edits mode, fallback, and location:

theme-agent config set mode auto
theme-agent config set fallback dark
theme-agent config set location 51.5072 -0.1276

A running daemon watches the file and live-reloads valid changes. A successful reload emits config_changed.

Validation

Latitude must be in [-90, 90], longitude in [-180, 180], and sun elevation in [-18, 18]. Explicit sun mode also requires a location. Invalid configuration is rejected rather than partially applied.

See Modes and scheduling for how system, sun, and fallback inputs resolve.

Hook timing and arguments

• on_light and on_dark run only when the effective theme transitions. They do not run merely because the daemon starts.
• on_start runs once after initial resolution, even if no transition occurred. Use it to reconcile tools at login.
• In an on_start argv element, {theme} expands to the current light or dark value.
• Every hook is a complete argv array. Element zero is the executable; the remaining elements are its arguments.
• Hooks run directly without a shell. $VAR, pipes, globs, and other shell interpolation are not supported.
• A leading ~ or ~/ is expanded in every argv element, including the executable.
• Hook processes start asynchronously. A launch failure is logged and does not stop resolution or broadcasting.

For example:

[hooks]
on_light = ["~/.local/bin/theme-apply", "--light"]
on_dark = ["~/.local/bin/theme-apply", "--dark"]
on_start = ["~/.local/bin/theme-apply", "--theme", "{theme}"]

Currently serialized but unused fields

theme.light, theme.dark, and neovim.enabled are part of the serialized schema, but the Rust daemon and bundled Lua plugin do not currently consume them. The plugin uses its own colorschemes and behavior options. Do not rely on these TOML fields to change a client until explicit plumbing is added.