Config defaults
The defaults Kanade starts from, exactly as kanade config defaults prints them. Every key is
optional; the comment above each one is the key’s own help text. The block is generated from the
repository’s Configuration page and copied verbatim, so it stays scannable rather than prose.
# the island snaps to its new shape and fades its content; the fade is 80 ms at 100% animation speed; KANADE_REDUCED_MOTION=1 or 0 overrides itreduced_motion = false
# the time an idle island shows: "24h" (14:05) or "12h" (2:05 PM), per outputclock = "24h"
[timings]# pointer resting on a Compact island before it peeks, ms 1-60000hover = 120# morph to a larger form, ms 1-60000expand = 144# one Surface replacing another, and a new track dissolving in, ms 1-60000surface_change = 176# morph to a smaller form, ms 1-60000collapse = 144# pointer out before a Peek or Surface collapses, ms 1-60000grace = 250# the OSD, and a workspace switch on the island, ms 1-60000osd = 1200
[theme]# accepted from older config files; no longer changes the shell theme# palette = "~/Pictures/wallpaper.jpg"
[shell]# separate keeps the Island and Dock in their own positions; combined puts both in one shell, with apps on either sidemode = "separate"# which top or bottom edge the combined shell hangs from; stored while Separate is activeedge = "top"# where along that edge the combined shell sits; stored while Separate is activealign = "center"
[appearance]# selects light or dark for Settings and apps; the Island, Dock and Banners follow the finish. Matugen derives both palettes from the wallpaper awww shows at startup or Kanade setstone = "dark"# what the Island, Dock and Banners are made of, tinted toward the wallpaper's hue in each: "tinted-solid", dark with light text, "paper", light with dark ink, or "blur", the tinted solid translucent over what the compositor blurs behind it, paper while `appearance.tone` is "light" (needs niri 26.04)finish = "tinted-solid"# sets the desktop color preference and paired GTK theme; writes the wallpaper colors for GTK, qt5ct/qt6ct, KDE apps, niri, kitty and Pywalfox. Kvantum gives way to Darkly or Fusion; GTK and Qt apps need restart. Other apps are unchangedsync = false# follow the desktop's reduced motion and higher contrast preferences (the settings portal): the first turns reduced_motion on, the second makes the Island, Dock and Banners a solid finish, with nothing written to your files; reduced_motion = true or KANADE_REDUCED_MOTION=1 win over a desktop that does not ask, KANADE_REDUCED_MOTION=0 over one that does; turning it on takes a restartaccessibility = true# how the Island and Dock settle: "bouncy" like macOS, "smooth" with no overshoot, "snappy", or "playful"motion = "bouncy"# installed family for shell labels; unset uses Open Sauce One. A family without a static SemiBold face renders regular weights, takes a restart# font = "Open Sauce One"# the size of everything Kanade draws, on top of each output's own scale: 100% is unchanged, 125% a quarter larger. Windows already open keep their size; the lock screen is not scaled, % 80-200scale = 100
[animation]# 100% is unchanged; higher values are faster. Interaction delays and countdowns do not change, % 25-400speed = 100
[island]# the edge of the screen the Island hangs fromedge = "top"# where along its edge the Island sitsalign = "center"# how wide the Surfaces with a list grow, as their content asks, px 520-800width = 520# how tall the Surfaces with a list grow, as their content asks, px 330-600height = 400# an idle Island slides past its edge, back as the pointer touches the edge under it or anything showsautohide = false# windows keep off the Island's strip of the screen, unless it autohides; off, it floats over themreserve = false# the wheel over the Island sets the volume while it shows Media or the volume; over anything else it does nothingwheel = true# a Bluetooth device connecting or going, the charger plugged in or out, a new sound output and a Wi-Fi network joined show on the Island for a moment, each while its Module is ondevice_events = true
[rest]# an idle Island shows the time; with it and the battery off, the Island hides as it does with autohide, per outputclock = true# an idle Island shows the battery's percent after the time, per outputbattery = false
[rest.peek]# the time's Peek shows the battery's percent beside the time, where an autohidden Island is seen, per outputbattery = true# the time's Peek shows the weather beside the date, per outputweather = true# the time's Peek shows the next event beside the date, per outputagenda = true
[privacy]# dots at the Island's trailing end while a microphone, camera or screen cast is in use, and the apps named in Controls, with whether a cast captures a window or a screen; not shown over a fullscreen windowindicators = true
[banners]# how a Banner comes in: "morph" out from under the Island, "drop" from the edge, or "fade"entrance = "morph"
[modules]# every Module is on unless set to false here; idle, dictation and screen-time are off unless set to true, takes a restartdictation = falseidle = falsescreen-time = false
[windows.apps]# app id = the .desktop file it belongs to, where Kanade's guess is wrong# jetbrains-idea = "intellij-idea-ultimate-edition"
[dock]# .desktop file ids, in the Dock's order# pinned = ["firefox", "kitty"]# the edge of the screen the Dock sits on; beside the Island, on its edge and side or either centered, it sits further in than the Island; wherever the Island grows over it, as an open Surface, it steps aside and fades back as the Island closesedge = "bottom"# where along its edge the Dock sitsalign = "center"# the Dock hides until the pointer touches the edge under it; beside the Island it always shows, as the pointer could not reach past the Island; merged with it, it folds into the Island as `merge = "fold"` doesautohide = false# windows keep off the Dock's strip of the screen, unless it autohides; off, it floats over themreserve = true# how much an icon grows under the pointer, its neighbors lessmagnification = "classic"# how big the icons are at rest; the gaps between and how far the swell under the pointer reaches grow with themsize = "medium"# how the Dock and the Island join where they share an edge and a side, along a top or bottom edge: crown, the Island rising from the Dock's middle; keystone, the Island the Dock's middle piece; fold, the Dock unfolding out of the Island under the pointer; off, the Dock beside the Island, further inmerge = "crown"
[battery]# at or below, a draining battery shows on the island, % 5-50low = 20# at or below, the battery interrupts and battery.critical_action counts down; one above battery.low counts as battery.low, % 2-30critical = 10# what a draining critical battery does after a 60 s countdown that Cancel or a charger stops: "none", "suspend", "hibernate" or "poweroff"critical_action = "none"
[media]# what moves beside a playing trackvisualizer = "bars"# the current line of a playing track's synced lyrics on the Media Surface, from a .lrc file beside a local track, or also from LRCLIB, which is told the track's title, artist, album and lengthlyrics = "off"
[timer.pomodoro]# how long a pomodoro's focus lasts, unless `kanade timer pomodoro` says, min 1-180work = 25# how long the break after a focus lasts, min 1-180break = 5# how long the break after the last round's focus lasts, min 1-180long_break = 15# how many focus rounds come before a long break, rounds 1-12rounds = 4
[live]# how long a live Activity from `kanade activity` shows without a word from its program, min 1-1440stale = 30
[brightness]# what sets the brightness: "backlight", an external monitor over "ddcci" (DDC/CI, needs the i2c-dev module and access to /dev/i2c-*), or "auto" for the backlight, else a monitor, takes a restartbackend = "auto"
[osd]# a keyboard layout switch shows as an OSD, with two or more layoutslayout = true
[notifications]# a notification arriving plays the sound it names, else a default, through pw-play or canberra-gtk-play; never under Do Not Disturbsound = false# while a fullscreen window covers the focused output, a non-Critical Banner waits and no notification sound plays; a Critical one, and one a rule lets bypass Do Not Disturb, still shows; waiting Banners show when it no longer covers, without the sound againfullscreen_silence = true# the sound of a notification whose sender and urgency name none: an absolute file path (a leading ~/ is your home) or a freedesktop sound name; unset plays message-new-instant, and a missing file is noted and replaced by it# sound_file = "~/Music/ding.oga"# the volume of a notification sound, for that sound alone and never the system volume; 0 plays none, and a rule's volume goes over it, % 0-100sound_volume = 100# the sound of a Low notification whose sender names none: a file, a freedesktop sound name or "off"; unset follows sound_file; file only# sound_low = "off"# the sound of a Normal notification whose sender names none: a file, a freedesktop sound name or "off"; unset follows sound_file; file only# sound_normal = "message-new-instant"# the sound of a Critical notification whose sender names none: a file, a freedesktop sound name or "off"; unset follows sound_file; never under Do Not Disturb; file only# sound_critical = "~/Music/alarm.oga"# per app: the first rule whose app, desktop_entry, category and summary piece all match, ignoring case, sets banner, history, sound (false, a file or a sound name), volume (%), bypass_dnd, timeout (ms) and urgency; file only# rules = [{ app = "Slack", banner = false }, { bypass_dnd = true, summary = "battery" }]
[desk]# the time and date in large plain text on the desktop, under every window, one per output; the clock itself takes no click, per outputclock = false# the corner of the output the Desk stands in, per outputclock_corner = "bottom-right"# previous, play or pause and next buttons for the player on the desktop, under every window, one set per output; only the buttons take the pointer; needs the media Module, per outputmedia = false# the temperature and condition on the desktop, from the forecast already fetched; nothing while the weather Module is off or there is no forecast; takes no click, per outputweather = false# the next event's time on the desktop, from the calendar; nothing while the calendar Module is off or there is no event; takes no click, per outputagenda = false# the next event's title on the Desk agenda; off, the line is the time and the countdown; the title only when this is on, per outputagenda_titles = false# the playing track's title and artist on the desktop; off, neither is shown, and the player is not read for them; needs the media Module, per outputmedia_titles = false# your notes on the desktop, newest last, in $XDG_STATE_HOME/kanade/desk-notes; a click on the card types into it in place and Escape keeps it; off, the card is not drawn and the file is not read, per outputnotes = false
[desk.place]# face = where it stands on the output, its top left corner in px from the output's top left: clock, weather, agenda, media or notes; a face given no place stands in the corner desk.clock_corner says, and dragging a face's handle sets this, per output# clock = { x = 40, y = 40 }
[controls]# the switches the Controls Surface shows, in order, each "name" or "name:size" (wifi, bluetooth, caffeine, dnd, night-light, focus, charge-limit, power-profile; half, full or icon, where wifi and bluetooth have no icon); at most three rows, a tile this machine cannot use, like the charge limit without a battery that has one, is left out; the pencil in Controls edits themtiles = ["wifi", "bluetooth", "caffeine", "dnd", "night-light", "focus"]
[wallpaper]# the images the Wallpapers Surface shows, else ~/Pictures/Wallpapers; an empty folder is filled once from the Favorites list at https://github.com/ItsTerm1n4l/Wallpapers# directory = "~/Pictures/Wallpapers"# on, a wallpaper picked in the shell (the Wallpapers Surface, `kanade wallpaper shuffle`) is set on that monitor alone; off, on every monitor. `kanade wallpaper set --output` names one either wayper_monitor = true# how awww moves to a new wallpaper: "simple" fades at its own pace, "fade" fades, "wipe" sweeps across, "grow" opens a circle and "outer" closes one, from the tile chosen on the Wallpapers Surface, else the middle, and "random" lets awww pick one each timetransition = "simple"# on, a moving image picked as the wallpaper is drawn by Kanade, at the speed it was made at, and pauses while the session is locked, niri's overview is open or a fullscreen window covers its monitor; off, awww shows such a file as its first picturemoving = false# how long a transition other than "simple" takes, ms 1-60000transition_duration = 1000
[launcher]# an app's own actions, like a browser's New Private Window, are rows of the Launcher once two letters are typedactions = true# Kanade's own commands, like Toggle Caffeine or Screenshot Area, are rows of the Launcher once two letters of their name are typed; pressing one runs itcommands = true# "island" opens the Launcher in the Island's own body; "detached" opens it in a window of its own, centred on the focused outputstyle = "island"# your own rows in the Launcher, each a title and a target: a url opened in the default browser, or an argv list run directly with no shell, a leading `~/` in a word being your home directory; `passes_query = true` adds the typed query as one last word and hides the row until something is typed, and a row that fits nothing does not hide the web's rows; a layer replaces the list below; file only# quicklinks = [{ title = "GitHub", url = "https://github.com" }, { argv = ["kitty", "-e", "vim", "~/notes.md"], title = "Notes" }, { argv = ["lookup"], passes_query = true, title = "Look up" }]
[calendar]# iCalendar (.ics) files and directories of them, read recursively, else $XDG_DATA_HOME/calendars# paths = ["~/.local/share/calendars", "~/Documents/holidays.ics"]# minutes before a timed event with no reminders of its own to remind of it, 0 for none, min 0-10080reminder = 0# https:// (or webcal://) addresses of public iCalendar feeds, fetched into read-only calendars; an address may hold a secret, so none is logged or shown# subscriptions = ["https://example.org/holidays.ics", "webcal://example.org/team.ics"]# minutes between fetches of each subscription, at least 30, min 30-1440subscription_interval = 60
[weather]# where the weather is for, as [latitude, longitude] in degrees, north and east positive; unset fetches nothing. Settings finds it from a place name# location = [52.52, 13.41]# the location's name, which the Weather Surface shows# place = "Berlin"# °C and km/h, or °F and mphunits = "metric"
[capture]# a screenshot `capture screenshot` saved opens in an editor on the focused output, to draw rectangles and arrows and save a copy beside it; off, only the saved notice shows. The pointer draws; Escape closes without writing and Ctrl+Z takes back the last shapeannotate = false
[recording]# how much of the picture a screen recording keeps: "low", "medium", "high" or "max". Each is one fixed quantizer for the encoder in use, so a still screen costs nothing and a busy one what it needs; each step changes the size of a busy picture by about a quarterquality = "high"# what encodes a screen recording as H.264: "vaapi" (the GPU through VA-API: Intel, AMD), "nvenc" (an NVIDIA GPU), "software" (libx264 on the CPU), or "auto" for the first that works, in that order; NVENC is not tried while VA-API works, so an NVIDIA GPU that sleeps stays asleep. One that does not work gives way to software, which `kanade doctor` and the log say. Read when a recording startsencoder = "auto"# the DRM render node VA-API encodes on, like /dev/dri/renderD128; unset finds an Intel or AMD one, the GPU that drives the display first, and never an NVIDIA one# device = "/dev/dri/renderD128"
[screen-time]# minutes of focused time before one notice that day, 0 for none, min 0-1440limit = 0# keep the focused window's title in the private screen-time file, off so only the app id is kepttitles = false
[gestures]# gesture name = the Kanade verb it runs, like "island collapse"; record a gesture with `kanade gesture record <name>`; never a program, which a hook or a verb of yours runs; file only# check = "island collapse"# circle = "launcher open"
[dictate]# where a dictation's text goes: "copy" puts it on the clipboard, "paste" puts it there and sends Ctrl+V to the focused window, "type" types it with wtype. Either of the last two falls back to the clipboard, marked sensitive, when the window in front is not the one you started in, is in dictate.never_in, or wtype failsinsert = "copy"# app ids, as niri names them (`niri msg windows`), whose windows only ever get the clipboard, like a password manager# never_in = ["org.keepassxc.KeePassXC"]
[night-light]# warms the screen through wlsunset: "off", "on" all day, or on a "schedule" from sunset to sunrisemode = "off"# the screen's color temperature while warm; lower is warmer, 6500 is neutral, K 1000-6500temperature = 4000# when the schedule warms the screen, as "HH:MM"; with night-light.sunrise it is the schedule, else the sun at weather.location is# sunset = "20:00"# when the schedule turns the screen neutral again, as "HH:MM"# sunrise = "07:00"
[focus]# Focus turns Do Not Disturb on, and off again if it was off beforednd = true# Focus keeps the session awake, and releases it again if it was not held beforecaffeine = true# Focus warms the screen, and turns the night light off again if it was off beforenight_light = false# what turns Focus on by itself, and off again when it ends, only if nobody turned Focus on or off meanwhile: "cast" is a screen cast running (needs the privacy Module); empty is never# auto = ["cast"]
[lock]# what the lock screen shows behind the clock: the wallpaper awww shows on that output "blurred", sharp as "wallpaper", "dimmed", or "solid"; solid also stands in for a wallpaper that is not png, jpeg, webp, gif or svgbackdrop = "blurred"# the PAM service that checks the password, a file of that name in /etc/pam.d; unset uses login. Letters, digits, dots, dashes and underscores. Only the first hidden prompt gets the password; an echoed or later one fails the check, and PAM's own messages show under the field. A name with no file refuses every lock# pam_service = "login"# seconds after the idle Module locks the session in which any key, click, scroll or pointer movement unlocks it without a password; never for `kanade lock`, a lock before sleep or a lock asked again after a failure; 0 is none, s 0-30grace = 0
[sddm]# the SDDM theme `kanade sddm` writes its look for, by its directory name; unset is Kanade's own, kanade# theme = "kanade"# what the login screen shows behind the clock: the wallpaper awww shows when `kanade sddm sync` runs, the image at sddm.background_path, the solid color sddm.surface, or "none", which writes no picturebackground = "wallpaper"# the image for sddm.background "path": png, jpeg, webp, gif or svg, a symbolic link to one is followed; its first frame# background_path = "~/Pictures/login.png"# the login screen's color where there is no picture, #rrggbb; unset is the theme's own# surface = "#0c0d11"# how far the login screen's picture is blurred, in pixels of the picture; 32 is the lock screen's, 0 is sharp, px 0-128blur = 32# how dark the login screen's picture is made, whole percent of black over it; 0 is none, % 0-100dim = 33# whether the shell writes the login screen's picture again whenever the wallpaper changes, with sddm.background "wallpaper", once root has made the overlay directory (`kanade sddm status` prints the command); off by default, as the file is readable by the login screen's own user and by anyone who can read the overlay directory, so it holds a picture of your desktopsync = false
[idle]# seconds idle before the screens fade toward dark, until the lock; any input brings them back; 0 is never, s 0-86400dim = 270# seconds idle before the session locks, as `kanade lock` does; 0 is never, s 0-86400lock = 300# seconds idle before niri powers the monitors off, back on at any input; never before the lock holds; 0 is never, s 0-86400screen_off = 330# seconds idle before the machine suspends, through logind; never before the lock holds; 0 is never, s 0-86400suspend = 0
[settings]# tell once, at the first start with checks that need attention, to open Settings' Health pagehealth_notice = true
[ui]# what `kanade ui describe` says of the windows, and so what an agent or script can read: "structure" is roles, names, states and places with every label and value `<redacted>`; "content" adds what notifications, the clipboard, the calendar and lyrics show (never a password), for debugging on this machine; "off" refuses `kanade ui` entirelydescribe = "structure"
[hooks]# a command run, as a list of strings with no shell, when niri holds the lock; the program is looked up on PATH, a leading ~/ in it is your home, and KANADE_HOOK names the event# lock = ["notify-send", "Kanade", "hook"]# a command run when the lock ends# unlock = ["notify-send", "Kanade", "hook"]# a command run when a wallpaper is set or shown, its path in KANADE_WALLPAPER# wallpaper = ["notify-send", "Kanade", "hook"]# a command run when appearance.tone changes, "dark" or "light" in KANADE_TONE# tone = ["notify-send", "Kanade", "hook"]# a command run when the charger goes in or out, "plugged" or "unplugged" in KANADE_CHARGER# charger = ["notify-send", "Kanade", "hook"]# a command run as the machine goes to sleep, before the lock is asked; sleep waits for it only until logind's delay ends# suspend = ["notify-send", "Kanade", "hook"]# a command run when the machine wakes, or a sleep failed# resume = ["notify-send", "Kanade", "hook"]# a command run when the shell has started, once every Module that is on has# started = ["notify-send", "Kanade", "hook"]# a command run when Do Not Disturb goes on or off, "on" or "off" in KANADE_DND# dnd = ["notify-send", "Kanade", "hook"]# a command run when the power profile changes, its name (power-saver, balanced or performance) in KANADE_POWER_PROFILE; not the one at start# power_profile = ["notify-send", "Kanade", "hook"]# a command run before logind is asked to end the session, after the countdown or at once; the log out waits for it up to hooks.timeout, and at most a few seconds# logout = ["notify-send", "Kanade", "hook"]# a command run before logind is asked to restart, after the countdown or at once; the restart waits for it up to hooks.timeout, and at most a few seconds# reboot = ["notify-send", "Kanade", "hook"]# a command run before logind is asked to power off, after the countdown or at once; the power off waits for it up to hooks.timeout, and at most a few seconds# poweroff = ["notify-send", "Kanade", "hook"]# a command still running after this is killed; one run of an event at a time, a fire meanwhile is dropped, s 1-300timeout = 10
[output."eDP-1"]# for the output of this name only, over the keys above from any file# clock = "24h"# rest.clock = true# rest.battery = false# rest.peek.battery = true# rest.peek.weather = true# rest.peek.agenda = true# desk.clock = false# desk.clock_corner = "bottom-right"# desk.media = false# desk.weather = false# desk.agenda = false# desk.agenda_titles = false# desk.media_titles = false# desk.notes = falseFor the layers these defaults sit under, and how to read or write one key, see Configuration. Keys are grouped by area on the pages linked there.