---
title: Configuration
description: Undertone's settings as a file you can keep in your dotfiles.
url: https://mpdreamz.github.io/undertone/reference/configuration
---

# Configuration
Undertone keeps its settings in a plain text file, `~/.config/undertone/config.toml` (under `$XDG_CONFIG_HOME` when
that is set), so you can keep them in your dotfiles and have every Mac look the same.
- **Edits apply on their own.** Undertone notices a change to the file within a second, whether you edit it, a
  dotfiles manager (chezmoi, stow, yadm) writes it, or a `git pull` brings it in. No restart.
- **Settings write it.** A change in Settings or the menu writes the whole file again, in the layout
  below. Comments of your own are lost when that happens; keep notes elsewhere, or make your changes in the file.
- **A link stays a link.** If `config.toml` is a symbolic link (stow, or chezmoi in symlink mode), Undertone writes to
  the file it points at.
- **Only settings.** What is showing now, when it last shuffled, and **Pause** stay in Undertone's own preferences, so
  a shuffle or a pause never changes the file.
- **No file, no problem.** Without one Undertone uses the defaults, and writes the file the first time you change a
  setting. **Open Config File** in the menu writes it and opens it.
- **Mistakes stay small.** A key or value Undertone cannot use falls back to that setting's default and the rest of the
  file still applies; the menu shows the first problem, and `undertone config --check` lists them all, by line.


## The file

Every setting, at its default (`undertone config --defaults` prints this):
```toml
# Undertone's settings. Undertone reads this file when it changes, and writes it (in this layout, without
# comments of your own) when you change a setting from its settings window or menu.
# https://mpdreamz.github.io/undertone/reference/configuration/

[style]
mode = "shuffle" 
always = "mesh"  # the style when mode = "always"
never = [] 

[tonality]
mode = "shuffle" 
always = "ember"  # the tonality when mode = "always"
never = [] 
hemisphere = "auto" 

# Effects go over every picture, in a fixed order: glass, halftone, vignette, bloom, posterize, paper, leak,
# dither, grain. Each has its own section; on = false turns it off and keeps its settings here.
[effects]
random = false 
random_never = [] 

[effects.vignette]
on = true
strength = 1.0 

[effects.grain]
on = true
amount = 0.035 

[effects.dither]
on = false
levels = 4 
cell = 1.0 

[effects.halftone]
on = false
spacing = 8.0 
angle = 45.0 

[effects.glass]
on = false
width = 36.0 
strength = 0.55 

[effects.bloom]
on = false
threshold = 0.45 
strength = 0.6 

[effects.leak]
on = false
strength = 1.0 
warmth = 1.0 

[effects.paper]
on = false
strength = 1.0 

[effects.posterize]
on = false
bands = 7 

[shuffle]
every = "never" 
on_wake = false 

[screen]
spaces = "same" 
hide_notch = false 
round_corners = false 

[title]
show = false
title = "{computer}" 
subtitle = "{user} · macOS {os}"

[motion]
lock_screen = false 
speed = "normal" 
movement = "normal" 
settle = 2.5 
easing = "ease-out" 
```

The file is a small part of [TOML](https://toml.io): sections, `key = value`, text in double quotes, numbers,
`true` and `false`, and `#` comments. A file needs only the keys you want to change.

## From the command line


|                                   |                                                                                                                                         |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `undertone config`                | Where the file is.                                                                                                                      |
| `undertone config --defaults`     | A file with every setting at its default, to start from.                                                                                |
| `undertone config --check [file]` | What Undertone cannot use in the file (or in `file`), by line; exits with 1 when there is anything, for a dotfiles repository's checks. |

Older settings move over on their own: from Undertone 0.3's preferences into the file, and a file in Undertone 0.4's
layout (with a `[picture]` section) is read and written again in this one. A locked style or tonality becomes
`mode = "always"`, random becomes shuffling among all, grain becomes `[effects.grain]`, and a chosen effect is turned
on.