Skip to main content

Themes

mecatui ships with three themes:

  • aztec: the default, with jade, turquoise, and gold on obsidian
  • mono: neutral greys with a blue accent
  • solar: a warm, light-leaning variant

Select one at launch:

mecatui --theme mono

You can also set MECATUI_THEME=mono. Use --list-themes to print the themes available to this launch.

Light terminals get a light theme automatically​

If you don't pass --theme/MECATUI_THEME and you're running in a real terminal, mecatui asks your terminal for its background color at startup. If the terminal reports a light background, mecatui switches to solar automatically. A dark background, no answer (some terminals and multiplexers don't respond), or piped/redirected output all keep the default aztec theme.

Passing --theme or MECATUI_THEME, including --theme aztec, skips this detection. Pin a theme to disable automatic selection.

Add a partial palette​

Theme files are JSON. A palette extends the Aztec base, so it only needs the slots it changes:

{
  "name": "midnight",
  "palette": {
    "accent": "#7C5CFF",
    "primary": "#5CC8FF",
    "error": "#FF5C7C"
  }
}

Save the file in one of these locations. Later locations take precedence when names collide:

  1. $XDG_CONFIG_HOME/mecatui/themes/ (normally ~/.config/mecatui/themes/)
  2. <workspace>/.mecatui/themes/
  3. <cwd>/.mecatui/themes/
  4. a directory passed with --theme-dir

Then choose it with --theme midnight or MECATUI_THEME=midnight. Themes are discovered at startup, so restart mecatui after adding or changing a file.

For all palette slots and the complete theming reference, see docs/tui.md.