Configuration

One live-reloaded KDL file drives everything: the mod key, input, binds, submaps, appearance, animations, rules and more.

atlaswm reads one file: $XDG_CONFIG_HOME/atlaswm/config.kdl (i.e. ~/.config/atlaswm/config.kdl). It's KDL, it's live-reloaded within a second of saving, and a parse error never takes the session down — the last good config keeps running and the error is logged. Your file only needs the lines you want to change; everything else falls back to the compiled-in defaults.

To start from a documented baseline:

atlasctl default-config > ~/.config/atlaswm/config.kdl

How it merges

• Sections override. Set appearance { border-width 0 } and only that key changes; the rest of appearance keeps its defaults.
• Binds merge. Same key pattern as a default = override it; a new pattern = added on top. You don't have to re-list every default bind.
• Bad config is inert. A typo, an unknown verb, a broken regex → the parse fails, the error is logged, and the previously-loaded config keeps running. The session never goes down over a config mistake; fix the file and save to re-apply (live reload).

Two things about keys:

• Binds follow the letter, not the physical key: Mod+q on azerty is the key that types q. Caps Lock and Num Lock never affect binds.
• input { xkb-layout "fr" } is how azerty works without XKB_DEFAULT_* env vars.

The main blocks

A quick map of what lives where. Each is optional; omit a block to take its defaults.

A minimal config

You rarely need more than a handful of lines. A common starting point:

mod "super"
gaps 8

input {
    xkb-layout "fr"
}

animations {
    enable #true
    duration-ms 150
    curve "ease-out-cubic"
}

spawn-at-startup "waybar"
spawn-at-startup "swaybg" "-i" "/path/to/wallpaper.png"

binds {
    "Mod+d" "spawn:wofi --show drun"
    "Mod+Print" "spawn:grim -g \"$(slurp)\" ~/shot.png"
}

That keeps every default bind, adds two of your own, picks Super as the mod, turns on 8 px gaps and animations, sets azerty, and autostarts a bar and wallpaper.

The full reference

Every key, with its compiled-in default value and an inline comment, lives in the configuration reference — reproduced verbatim from DEFAULT_CONFIG (a unit test keeps it from drifting from the code). It's the authoritative list:

• In the repo: docs/config-reference.md
• Or print it locally: atlasctl default-config

The reference is the place to copy exact syntax for rules, anchors, outputs, idle, the width/height ratio verbs, marks, groups and the rest — all shown as commented examples you can uncomment and edit.