Teal / Launcher

When RETUI feels haunted.

A launcher with this many moving parts will occasionally show you something that does not match the thing you just changed. The useful question is not “which random reset should I try?” It is “which layer has gone stale?”

Use the smallest recovery first

I do not like troubleshooting rituals where every problem ends with wiping the app. RETUI has three ordinary tools that answer three different questions.

refresh

Reload apps, aliases, music, contacts, and RSS data. Use it when the information is stale but the interface itself is fine.

restart

Reload the Launcher UI and reread modified values. Use it after larger visual changes or direct file edits.

debug -settings

Print the effective colour, font, notification, music, wallpaper, and runtime settings that RETUI is actually using.

debug -presets

Show the preset directory plus every saved and built-in preset RETUI can currently see.

Refresh the source. Restart the surface. Inspect the state. That order solves a surprising amount without destroying anything.

If the colour is wrong, find out who is in charge

The saved value and the effective value are not always the same. Wallpaper auto-colour can deliberately supply an effective palette over the values in the XML files.

debug -theme
# look for auto_color_pick and Effective colors

If `auto_color_pick` is true, changing `theme.xml` may be perfectly valid while the wallpaper-derived colour remains visible. Turn auto-colour off when you want the saved values to take control, then restart.

config -set auto_color_pick false
restart

If a saved look drifted, apply it again with `preset -apply <name>`. Applying a preset disables auto-colour and restores its theme and suggestion colours. The Presets post explains that boundary in more detail.

If the content is stale, refresh the owner

An installed app that does not appear, an alias that still behaves like its old line, or contacts that feel behind are usually data refresh problems.

App missing

Run `apps -lsh` first. A hidden app is still installed; RETUI simply keeps it out of normal suggestions and drawer views. Use `apps -show <app>` to restore it.

Install or uninstall not reflected

Run `refresh` so the app registry is filled again.

Alias edit not reflected

Save `alias.txt`, then run `refresh` to reload the alias manager.

RSS or contacts stale

`refresh` also asks those managers to reload their current data.

The Apps post covers hidden apps and groups. The Aliases post covers the text file and workflow rules.

Fonts, notifications, and music each have two truths

These features sit between RETUI and Android, so there is usually a saved preference and a system capability involved.

Font reverted

Check `system_font` and `font_file` in `debug -settings`. When `system_font` is true, the system face wins. Reconfirm the custom font in Appearance > Fonts.

No notification access

Run `notifications -access`, then allow RETUI in Android's notification-listener settings.

Notification in the wrong surface

Inspect `notification_terminal` and `notification_output`. The notification terminal and printed output history are separate destinations.

Music panel feels wrong

Inspect `music_enabled`, `music_widget`, `music_widget_auto_show`, and `music_preferred_package`, then check the chosen app under Settings > Integrations.

The music surface is intentionally a RETUI visualiser, not a clone of another app's Android widget. A different layout is not automatically a failed connection.

Keep evidence before changing more things

If the saved state looks correct and the screen still does not, capture the mismatch before another edit makes it disappear.

debug -settings
debug -presets
tui -about

Add what you expected, what appeared instead, the command or setting that caused it, and whether `refresh` or `restart` changed anything. A screenshot helps with layout and colour issues. Settings > System & Support > View Crash Log opens `crash.txt` when RETUI has recorded one.

You can send feedback from that same Settings section or use the GitHub link when the problem belongs in the open-source issue tracker.

The nuclear option should look nuclear

`tui -reset` removes the contents of the RETUI folder and reloads default settings. It is not a stronger version of `restart`, and it should never be the first troubleshooting step.

Create a personal backup in Settings before using it if the current setup contains anything you care about. A repeatable colour state can also be protected as a preset, but remember that a preset does not contain the rest of the Launcher.

RETUI should be understandable even when it misbehaves. The terminal is not decoration here. It is where the Launcher can tell you what it thinks is true.