# How to Configure Tuicr Themes: CLI Flags, Config Files, and Custom Palettes

> Learn how to configure Tuicr themes using CLI flags, config files, and custom palettes. Master Tuicr theming for a personalized experience.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**Tuicr themes are configured via the `--theme` CLI flag, the `theme` key in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml), or custom `.tmTheme` files placed in the themes directory, with all color definitions centralized in the `Theme` struct in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs).**

Tuicr is a terminal-based code review tool that supports extensive visual customization through its theme system. You can configure Tuicr themes using command-line arguments, configuration files, or custom TextMate theme files to match your preferred color palette. The architecture separates theme definitions from UI rendering, allowing you to switch palettes without modifying the application code.

## Understanding the Theme System Architecture

The core of Tuicr’s appearance is the **Theme** struct defined in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 101-138). This struct encapsulates every color used by the interface, including panel backgrounds, diff highlights, file-status indicators, comment-type hues, and status-bar styling.

Tuicr ships with **nine built-in preset themes**: Solarized, Catppuccin, Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest. These are implemented as constructor methods (e.g., `Theme::dark()`, `Theme::light()`) in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 140-400). The application uses **syntect** to parse TextMate theme files, enabling support for the standard `.tmTheme` format.

## Selecting a Built-In Theme

### Using the Command-Line Flag

The fastest way to change themes is the `--theme` flag, which overrides any configuration file setting. Launch Tuicr with your preferred preset:

```bash
tuicr --theme solarized_dark

```

This flag accepts any built-in theme name (such as `catppuccin_mocha`, `github_dark`, or `nord`) and applies it immediately on startup.

### Using the Configuration File

For persistent preferences, set the `theme` key in your [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml). Tuicr follows the XDG Base Directory specification:

- **Unix/Linux/macOS**: `$XDG_CONFIG_HOME/tuicr/config.toml` (typically `~/.config/tuicr/config.toml`)
- **Windows**: `%APPDATA%\tuicr\config.toml`

Create or edit the file to include:

```toml
theme = "catppuccin_mocha"

```

If no theme is specified via CLI or config, Tuicr falls back to `Theme::default()`, which currently returns `Theme::dark()`. The configuration is parsed in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs), which exposes both the `theme` key and the `themes_dir` helper function.

## Creating and Loading Custom Themes

Tuicr supports user-provided syntax-highlighting themes through the **themes directory** mechanism, implemented via `crate::config::themes_dir` (see [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) line 16).

### Preparing Your Custom Theme File

Create a custom palette using the **TextMate theme format** (`.tmTheme`). These XML-based files define color scopes for syntax highlighting and UI elements. Tuicr loads these using `syntect::parsing::ThemeSet::load_from_reader`, ensuring compatibility with existing editor themes.

### Installing Custom Themes

Place your `.tmTheme` file in the appropriate directory for your platform:

- **Unix**: `$XDG_CONFIG_HOME/tuicr/themes/` (usually `~/.config/tuicr/themes/`)
- **Windows**: `%APPDATA%\tuicr\themes\`

The filename (without the `.tmTheme` extension) becomes the theme identifier. For example, `my-custom.tmTheme` is referenced as `my-custom`.

### Activating Custom Themes

Reference your custom theme using the same methods as built-ins:

```bash
tuicr --theme my-custom

```

Or in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml):

```toml
theme = "my-custom"

```

## How Theme Colors Are Applied at Runtime

When Tuicr initializes, the `App` struct stores the selected theme in a `theme: Theme` field. The application uses helper functions in [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) to translate `Theme` fields into `ratatui::style::Style` objects consumed by the rendering engine.

Key style functions include:

- **Diff addition styling**: `styles::diff_add_style(&theme)` (see [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) line 13)
- **Status bar background**: `styles::status_bar_style(&theme)` (see [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) line 65)

UI modules such as [`src/ui/app_layout.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/app_layout.rs), [`src/ui/status_bar.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/status_bar.rs), and [`src/ui/submit_modals.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/submit_modals.rs) obtain the current theme from the `App` instance and apply these style helpers. This ensures a single source of truth for colors throughout the interface, whether you are viewing diffs, reading comments, or navigating the submission modal.

## Summary

- **Theme definitions** live in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs), with built-in presets covering popular palettes like Solarized, Catppuccin, and Nord.
- **Configuration** accepts the `--theme` CLI flag or the `theme` key in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) located in the XDG config directory.
- **Custom themes** use standard `.tmTheme` files placed in `tuicr/themes/` under your config directory, loaded via syntect.
- **Runtime application** occurs through the `App` struct and [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) helpers, ensuring consistent coloring across all UI components.

## Frequently Asked Questions

### Where does Tuicr look for custom theme files?

Tuicr searches for `.tmTheme` files in the themes subdirectory of your configuration folder: `$XDG_CONFIG_HOME/tuicr/themes/` on Unix systems or `%APPDATA%\tuicr\themes\` on Windows. The loader uses the `themes_dir` helper from [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) to resolve this path dynamically based on platform conventions.

### Can I use my existing VS Code or Sublime Text themes?

Yes, provided they are in the **TextMate `.tmTheme` format**. Tuicr uses syntect’s `ThemeSet::load_from_reader` to parse these files, so any standard TextMate theme compatible with syntect will work. Simply copy the `.tmTheme` file into your Tuicr themes directory and reference it by filename.

### Why does my theme change not apply immediately?

Theme selection happens at application startup in [`src/app/init.rs`](https://github.com/agavra/tuicr/blob/main/src/app/init.rs) (or [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs)). The `App` struct initializes with a specific `Theme` instance, and there is currently no runtime hot-reloading mechanism. You must restart Tuicr after changing the `theme` value in [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) or switching custom theme files.

### What is the default theme if I don't specify one?

If no theme is provided via `--theme` or configuration, Tuicr calls `Theme::default()`, which currently returns `Theme::dark()`. This fallback is defined in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) and provides a dark palette optimized for terminal readability until you configure a specific preference.