Basic Configuration

Sweets is configured in Lua. It loads the installed defaults first, then your personal file as an override.

Create a personal configuration

sweets --init-config

This creates ~/.config/sweets/sweets.lua with commented examples. It never overwrites an existing file, and it checks the result.

Put only the values you want to change in ~/.config/sweets/sweets.lua:

sweets.general({
    mod_key = "SUPER",
})

sweets.gaps({
    inner = 12,
    outer = 12,
    smart = true,
})

sweets.bind("MOD+D", "spawn", { "fuzzel" })

Load order

PREFIX follows the binary. /usr/bin/sweets reads /usr/share/sweets/sweets.lua, /usr/local/bin/sweets reads /usr/local/share/sweets/sweets.lua. XDG_CONFIG_HOME is honored when set.

With neither file present, Sweets starts with built-in defaults and a small set of emergency bindings.

How the layers combine

Your file does not replace the installed one wholesale. Each API merges differently:

A singleton such as sweets.general, sweets.layout, or sweets.gaps may be declared once per layer. Declaring one twice in the same layer, includes counted, is an error.

Validate

sweets --check-config              # installed and personal together
sweets --check-config ./test.lua   # one file on its own

A successful check prints the resolved path and exits 0. Syntax errors, unknown fields, wrong types, duplicate declarations, and unsafe include paths exit nonzero with the failing source and message. Neither form opens a Wayland socket.

Reload

Sweets watches the installed file, your file, and every included file, and reloads on save. To reload manually, press MOD+Shift+R or run:

sweets msg reload

A reload is all or nothing. A rejected candidate leaves the last valid configuration active and shows the error on every monitor until you fix it.

Inspect the active path, generation, and latest error:

sweets msg config

Individual pages note when a valid reload affects only future actions or future windows.

The sweets table

The global sweets table is the only API available to your configuration.

Unknown names and fields are rejected.

Strict globals

Reading an undeclared global rejects the configuration. This catches typos that Lua would otherwise turn into a silently absent field:

local enabled = true
sweets.pointer({ follow_focus = enabled })  -- valid

sweets.input({ natural_scroll = falsed })   -- error: unknown global `falsed`

Declare variables before reading them. An explicit nil still omits the entry as usual.

Sandbox

Lua functions, loops, tables, and the string, table, math, and utf8 libraries are available. Filesystem, process, and native-module access is not: io, os, package, require, debug, dofile, loadfile, load, pcall, xpcall, collectgarbage, and print are all removed.

Use sweets.include instead of require, and sweets.exec_once or a spawn binding to start programs. Commands are argument arrays and are never passed to a shell.

Each load is bounded:

Exceeding a limit rejects the configuration like any other error. Numbers must be finite; math.huge and 0/0 are rejected.

Next steps

• Split the configuration across files
• General settings for workspaces and focus
• Key bindings for actions and commands