Merge branch 'master' into bat_config_dir_docs

21 files changed, 808 insertions, 114 deletions

diff --git a/.gitignore b/.gitignore
index a3ea8cff..fbfe6ac6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,7 @@
 **/*.rs.bk
 
 # Generated files
+/assets/completions/_bat.ps1
 /assets/completions/bat.bash
 /assets/completions/bat.fish
 /assets/completions/bat.zsh
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1dd80c48..fdbbf867 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 - Syntax highlighting for JavaScript files that start with `#!/usr/bin/env bun` #2913 (@sharunkumar)
 - `bat --strip-ansi={never,always,auto}` to remove ANSI escape sequences from bat's input, see #2999 (@eth-p)
 - Add or remove individual style components without replacing all styles #2929 (@eth-p)
+- Automatically choose theme based on the terminal's color scheme, see #2896 (@bash)
 - Add option `--binary=as-text` for printing binary content, see issue #2974 and PR #2976 (@einfachIrgendwer0815)
 
 ## Bugfixes
@@ -78,6 +79,9 @@
   - [BREAKING] `SyntaxMapping::mappings` is replaced by `SyntaxMapping::{builtin,custom,all}_mappings`
 - Make `Controller::run_with_error_handler`'s error handler `FnMut`, see #2831 (@rhysd)
 - Improve compile time by 20%, see #2815 (@dtolnay)
+- Add `theme::theme` for choosing an appropriate theme based on the
+  terminal's color scheme, see #2896 (@bash)
+  - [BREAKING] Remove `HighlightingAssets::default_theme`. Use `theme::default_theme` instead.
 
 # v0.24.0
 
diff --git a/Cargo.lock b/Cargo.lock
index 0f242845..a6d47a19 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -149,6 +149,7 @@ dependencies = [
  "shell-words",
  "syntect",
  "tempfile",
+ "terminal-colorsaurus",
  "thiserror",
  "toml",
  "unicode-width",
@@ -626,6 +627,12 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7dfda62a12f55daeae5015f81b0baea145391cb4520f86c248fc615d72640d12"
 
 [[package]]
+name = "hermit-abi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d231dfb89cfffdbc30e7fc41579ed6066ad03abda9e567ccafae602b97ec5024"
+
+[[package]]
 name = "home"
 version = "0.5.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -751,9 +758,9 @@ checksum = "b5e6163cb8c49088c2c36f57875e58ccd8c87c7427f7fbd50ea6710b2f3f2e8f"
 
 [[package]]
 name = "memchr"
-version = "2.6.4"
+version = "2.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f665ee40bc4a3c5590afb1e9677db74a508659dfd71e126420da8274909a0167"
+checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
 
 [[package]]
 name = "miniz_oxide"
@@ -765,6 +772,18 @@ dependencies = [
 ]
 
 [[package]]
+name = "mio"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4929e1f84c5e54c3ec6141cd5d8b5a5c055f031f80cf78f2072920173cb4d880"
+dependencies = [
+ "hermit-abi",
+ "libc",
+ "wasi",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
 name = "nix"
 version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -1309,6 +1328,30 @@ dependencies = [
 ]
 
 [[package]]
+name = "terminal-colorsaurus"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f99bb1dc5cde9eada5a8f466641240f9d5b9f55291d675df4160b097fbfa42e"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "memchr",
+ "mio",
+ "terminal-trx",
+]
+
+[[package]]
+name = "terminal-trx"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d4c86910e10c782a02d3b7606de43cf7ebd80e1fafdca8e49a0db2b0d4611f0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
 name = "terminal_size"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
diff --git a/Cargo.toml b/Cargo.toml
index 67327460..f0a80346 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -68,6 +68,7 @@ bytesize = { version = "1.3.0" }
 encoding_rs = "0.8.35"
 os_str_bytes = { version = "~7.0", optional = true }
 run_script = { version = "^0.10.1", optional = true}
+terminal-colorsaurus = "0.4"
 
 [dependencies.git2]
 version = "0.19"
diff --git a/README.md b/README.md
index 14c264a8..c09d0e36 100644
--- a/README.md
+++ b/README.md
@@ -482,8 +482,10 @@ the following command (you need [`fzf`](https://github.com/junegunn/fzf) for thi
 bat --list-themes | fzf --preview="bat --theme={} --color=always /path/to/file"
 ```
 
-`bat` looks good on a dark background by default. However, if your terminal uses a
-light background, some themes like `GitHub` or `OneHalfLight` will work better for you.
+`bat` automatically picks a fitting theme depending on your terminal's background color.
+You can use the `--theme-light` / `--theme-light` options or the `BAT_THEME_DARK` / `BAT_THEME_LIGHT` environment variables
+to customize the themes used. This is especially useful if you frequently switch between dark and light mode.
+
 You can also use a custom theme by following the
 ['Adding new themes' section below](https://github.com/sharkdp/bat#adding-new-themes).
 
diff --git a/assets/completions/_bat.ps1.in b/assets/completions/_bat.ps1.in
index c0c151e1..b6f62aae 100644
--- a/assets/completions/_bat.ps1.in
+++ b/assets/completions/_bat.ps1.in
@@ -37,6 +37,8 @@ Register-ArgumentCompleter -Native -CommandName '{{PROJECT_EXECUTABLE}}' -Script
             [CompletionResult]::new('-m', 'm', [CompletionResultType]::ParameterName, 'Use the specified syntax for files matching the glob pattern (''*.cpp:C++'').')
             [CompletionResult]::new('--map-syntax', 'map-syntax', [CompletionResultType]::ParameterName, 'Use the specified syntax for files matching the glob pattern (''*.cpp:C++'').')
             [CompletionResult]::new('--theme', 'theme', [CompletionResultType]::ParameterName, 'Set the color theme for syntax highlighting.')
+            [CompletionResult]::new('--theme-dark', 'theme', [CompletionResultType]::ParameterName, 'Set the color theme for syntax highlighting for dark backgrounds.')
+            [CompletionResult]::new('--theme-light', 'theme', [CompletionResultType]::ParameterName, 'Set the color theme for syntax highlighting for light backgrounds.')
             [CompletionResult]::new('--style', 'style', [CompletionResultType]::ParameterName, 'Comma-separated list of style elements to display (*default*, auto, full, plain, changes, header, header-filename, header-filesize, grid, rule, numbers, snip).')
             [CompletionResult]::new('-r', 'r', [CompletionResultType]::ParameterName, 'Only print the lines from N to M.')
             [CompletionResult]::new('--line-range', 'line-range', [CompletionResultType]::ParameterName, 'Only print the lines from N to M.')
diff --git a/assets/completions/bat.bash.in b/assets/completions/bat.bash.in
index f314bb25..90931f24 100644
--- a/assets/completions/bat.bash.in
+++ b/assets/completions/bat.bash.in
@@ -113,6 +113,13 @@ _bat() {
 		return 0
 		;;
 	--theme)
+    	local IFS=$'\n'
+    	COMPREPLY=($(compgen -W "auto${IFS}auto:always${IFS}auto:system${IFS}dark${IFS}light${IFS}$("$1" --list-themes)" -- "$cur"))
+                    __bat_escape_completions
+    	return 0
+    	;;
+	--theme-dark | \
+	--theme-light)
 		local IFS=$'\n'
 		COMPREPLY=($(compgen -W "$("$1" --list-themes)" -- "$cur"))
                 __bat_escape_completions
@@ -170,6 +177,8 @@ _bat() {
 			--map-syntax
 			--ignored-suffix
 			--theme
+			--theme-dark
+			--theme-light
 			--list-themes
 			--squeeze-blank
 			--squeeze-limit
diff --git a/assets/completions/bat.fish.in b/assets/completions/bat.fish.in
index 788f71b0..e2712706 100644
--- a/assets/completions/bat.fish.in
+++ b/assets/completions/bat.fish.in
@@ -129,6 +129,14 @@ set -l tabs_opts '
     8\t
 '
 
+set -l special_themes '
+    auto\tdefault,\ Choose\ a\ theme\ based\ on\ dark\ or\ light\ mode
+    auto:always\tChoose\ a\ theme\ based\ on\ dark\ or\ light\ mode
+    auto:system\tChoose\ a\ theme\ based\ on\ dark\ or\ light\ mode
+    dark\tUse\ the\ theme\ specified\ by\ --theme-dark
+    light\tUse\ the\ theme\ specified\ by\ --theme-light
+'
+
 # Completions:
 
 complete -c $bat -l acknowledgements -d "Print acknowledgements" -n __fish_is_first_arg
@@ -203,7 +211,11 @@ complete -c $bat -l tabs -x -a "$tabs_opts" -d "Set tab width" -n __bat_no_excl_
 
 complete -c $bat -l terminal-width -x -d "Set terminal <width>, +<offset>, or -<offset>" -n __bat_no_excl_args
 
-complete -c $bat -l theme -x -a "(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme" -n __bat_no_excl_args
+complete -c $bat -l theme -x -a "$special_themes(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme" -n __bat_no_excl_args
+
+complete -c $bat -l theme-dark -x -a "(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme for dark backgrounds" -n __bat_no_excl_args
+
+complete -c $bat -l theme-light -x -a "(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme for light backgrounds" -n __bat_no_excl_args
 
 complete -c $bat -s V -l version -f -d "Show version information" -n __fish_is_first_arg
 
diff --git a/assets/completions/bat.zsh.in b/assets/completions/bat.zsh.in
index 7d03abb3..76b981b6 100644
--- a/assets/completions/bat.zsh.in
+++ b/assets/completions/bat.zsh.in
@@ -42,7 +42,9 @@ _{{PROJECT_EXECUTABLE}}_main() {
         --decorations='[specify when to show the decorations]:when:(auto never always)'
         --paging='[specify when to use the pager]:when:(auto never always)'
         '(-m --map-syntax)'{-m+,--map-syntax=}'[map a glob pattern to an existing syntax name]: :->syntax-maps'
-        '(--theme)'--theme='[set the color theme for syntax highlighting]:theme:->themes'
+        '(--theme)'--theme='[set the color theme for syntax highlighting]:theme:->theme_preferences'
+        '(--theme-dark)'--theme-dark='[set the color theme for syntax highlighting for dark backgrounds]:theme:->themes'
+        '(--theme-light)'--theme-light='[set the color theme for syntax highlighting for light backgrounds]:theme:->themes'
         '(: --list-themes --list-languages -L)'--list-themes'[show all supported highlighting themes]'
         --style='[comma-separated list of style elements to display]: : _values "style [default]"
             default auto full plain changes header header-filename header-filesize grid rule numbers snip'
@@ -82,7 +84,13 @@ _{{PROJECT_EXECUTABLE}}_main() {
 
         themes)
             local -a themes expl
-            themes=( ${(f)"$(_call_program themes {{PROJECT_EXECUTABLE}} --list-themes)"} )
+            themes=(${(f)"$(_call_program themes {{PROJECT_EXECUTABLE}} --list-themes)"} )
+
+            _wanted themes expl 'theme' compadd -a themes && ret=0
+        ;;
+        theme_preferences)
+            local -a themes expl
+            themes=(auto dark light auto:always auto:system ${(f)"$(_call_program themes {{PROJECT_EXECUTABLE}} --list-themes)"} )
 
             _wanted themes expl 'theme' compadd -a themes && ret=0
         ;;
diff --git a/assets/manual/bat.1.in b/assets/manual/bat.1.in
index 2bc0a3a5..ccc70629 100644
--- a/assets/manual/bat.1.in
+++ b/assets/manual/bat.1.in
@@ -152,9 +152,38 @@ will use JSON syntax, and ignore '.dev'
 .HP
 \fB\-\-theme\fR <theme>
 .IP
-Set the theme for syntax highlighting. Use '\-\-list\-themes' to see all available themes.
-To set a default theme, add the '\-\-theme="..."' option to the configuration file or
-export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
+Set the theme for syntax highlighting. Use \fB\-\-list\-themes\fP to see all available themes.
+To set a default theme, add the \fB\-\-theme="..."\fP option to the configuration file or
+export the \fBBAT_THEME\fP environment variable (e.g.: \fBexport BAT_THEME="..."\fP).
+
+Special values:
+.RS
+.IP "auto (\fIdefault\fR)"
+Picks a dark or light theme depending on the terminal's colors.
+Use \fB-\-theme\-light\fR and \fB-\-theme\-dark\fR to customize the selected theme.
+.IP "auto:always"
+Variation of \fBauto\fR where where the terminal's colors are detected even when the output is redirected.
+.IP "auto:system (macOS only)"
+Variation of \fBauto\fR where the color scheme is detected from the system-wide preference instead.
+.IP "dark"
+Use the dark theme specified by \fB-\-theme-dark\fR.
+.IP "light"
+Use the light theme specified by \fB-\-theme-light\fR.
+.RE
+.HP
+\fB\-\-theme\-dark\fR <theme>
+.IP
+Sets the theme name for syntax highlighting used when the terminal uses a dark background.
+To set a default theme, add the \fB\-\-theme-dark="..."\fP option to the configuration file or
+export the \fBBAT_THEME_DARK\fP environment variable (e.g. \fBexport BAT_THEME_DARK="..."\fP).
+This option only has an effect when \fB\-\-theme\fP option is set to \fBauto\fR or \fBdark\fR.
+.HP
+\fB\-\-theme\-light\fR <theme>
+.IP
+Sets the theme name for syntax highlighting used when the terminal uses a dark background.
+To set a default theme, add the \fB\-\-theme-dark="..."\fP option to the configuration file or
+export the \fBBAT_THEME_LIGHT\fP environment variable (e.g. \fBexport BAT_THEME_LIGHT="..."\fP).
+This option only has an effect when \fB\-\-theme\fP option is set to \fBauto\fR or \fBlight\fR.
 .HP
 \fB\-\-list\-themes\fR
 .IP
@@ -307,7 +336,7 @@ To use the preprocessor, call:
 
 \fB{{PROJECT_EXECUTABLE}} --lessopen\fR
 
-Alternatively, the preprocessor may be enabled by default by adding the '\-\-lessopen' option to the configuration file. 
+Alternatively, the preprocessor may be enabled by default by adding the '\-\-lessopen' option to the configuration file.
 
 To temporarily disable the preprocessor if it is enabled by default, call:
 
@@ -323,7 +352,7 @@ Enable the $LESSOPEN preprocessor.
 .IP
 Disable the $LESSOPEN preprocessor if enabled (overrides --lessopen)
 .PP
-For more information, see the "INPUT PREPROCESSOR" section of less(1).  
+For more information, see the "INPUT PREPROCESSOR" section of less(1).
 
 .SH "MORE INFORMATION"
 
diff --git a/doc/long-help.txt b/doc/long-help.txt
index 87fb5d96..85d595b9 100644
--- a/doc/long-help.txt
+++ b/doc/long-help.txt
@@ -119,6 +119,27 @@ Options:
           Set the theme for syntax highlighting. Use '--list-themes' to see all available themes. To
           set a default theme, add the '--theme="..."' option to the configuration file or export
           the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
+          
+          Special values:
+          
+            * auto: Picks a dark or light theme depending on the terminal's colors (default).
+                    Use '--theme-light' and '--theme-dark' to customize the selected theme.
+              * auto:always: Detect the terminal's colors even when the output is redirected.
+              * auto:system: Detect the color scheme from the system-wide preference (macOS only).
+            * dark: Use the dark theme specified by '--theme-dark'.
+            * light: Use the light theme specified by '--theme-light'.
+
+      --theme-light <theme>
+          Sets the theme name for syntax highlighting used when the terminal uses a light
+          background. Use '--list-themes' to see all available themes. To set a default theme, add
+          the '--theme-light="..." option to the configuration file or export the BAT_THEME_LIGHT
+          environment variable (e.g. export BAT_THEME_LIGHT="...").
+
+      --theme-dark <theme>
+          Sets the theme name for syntax highlighting used when the terminal uses a dark background.
+          Use '--list-themes' to see all available themes. To set a default theme, add the
+          '--theme-dark="..." option to the configuration file or export the BAT_THEME_DARK
+          environment variable (e.g. export BAT_THEME_DARK="...").
 
       --list-themes
           Display a list of supported themes for syntax highlighting.
diff --git a/doc/short-help.txt b/doc/short-help.txt
index 16b9eb05..ba06ef30 100644
--- a/doc/short-help.txt
+++ b/doc/short-help.txt
@@ -43,6 +43,10 @@ Options:
           Use the specified syntax for files matching the glob pattern ('*.cpp:C++').
       --theme <theme>
           Set the color theme for syntax highlighting.
+      --theme-light <theme>
+          Sets the color theme for syntax highlighting used for light backgrounds.
+      --theme-dark <theme>
+          Sets the color theme for syntax highlighting used for dark backgrounds.
       --list-themes
           Display all supported highlighting themes.
   -s, --squeeze-blank
diff --git a/src/assets.rs b/src/assets.rs
index 9655553d..d32ccbd4 100644
--- a/src/assets.rs
+++ b/src/assets.rs
@@ -13,6 +13,7 @@ use crate::error::*;
 use crate::input::{InputReader, OpenedInput};
 use crate::syntax_mapping::ignored_suffixes::IgnoredSuffixes;
 use crate::syntax_mapping::MappingTarget;
+use crate::theme::{default_theme, ColorScheme};
 use crate::{bat_warning, SyntaxMapping};
 
 use lazy_theme_set::LazyThemeSet;
@@ -69,57 +70,6 @@ impl HighlightingAssets {
         }
     }
 
-    /// The default theme.
-    ///
-    /// ### Windows and Linux
-    ///
-    /// Windows and most Linux distributions has a dark terminal theme by
-    /// default. On these platforms, this function always returns a theme that
-    /// looks good on a dark background.
-    ///
-    /// ### macOS
-    ///
-    /// On macOS the default terminal background is light, but it is common that
-    /// Dark Mode is active, which makes the terminal background dark. On this
-    /// platform, the default theme depends on
-    /// ```bash
-    /// defaults read -globalDomain AppleInterfaceStyle
-    /// ```
-    /// To avoid the overhead of the check on macOS, simply specify a theme
-    /// explicitly via `--theme`, `BAT_THEME`, or `~/.config/bat`.
-    ///
-    /// See <https://github.com/sharkdp/bat/issues/1746> and
-    /// <https://github.com/sharkdp/bat/issues/1928> for more context.
-    pub fn default_theme() -> &'static str {
-        #[cfg(not(target_os = "macos"))]
-        {
-            Self::default_dark_theme()
-        }
-        #[cfg(target_os = "macos")]
-        {
-            if macos_dark_mode_active() {
-                Self::default_dark_theme()
-            } else {
-                Self::default_light_theme()
-            }
-        }
-    }
-
-    /**
-     * The default theme that looks good on a dark background.
-     */
-    fn default_dark_theme() -> &'static str {
-        "Monokai Extended"
-    }
-
-    /**
-     * The default theme that looks good on a light background.
-     */
-    #[cfg(target_os = "macos")]
-    fn default_light_theme() -> &'static str {
-        "Monokai Extended Light"
-    }
-
     pub fn from_cache(cache_path: &Path) -> Result<Self> {
         Ok(HighlightingAssets::new(
             SerializedSyntaxSet::FromFile(cache_path.join("syntaxes.bin")),
@@ -248,7 +198,10 @@ impl HighlightingAssets {
                     bat_warning!("Unknown theme '{}', using default.", theme)
                 }
                 self.get_theme_set()
-                    .get(self.fallback_theme.unwrap_or_else(Self::default_theme))
+                    .get(
+                        self.fallback_theme
+                            .unwrap_or_else(|| default_theme(ColorScheme::Dark)),
+                    )
                     .expect("something is very wrong if the default theme is missing")
             }
         }
@@ -399,26 +352,6 @@ fn asset_from_cache<T: serde::de::DeserializeOwned>(
         .map_err(|_| format!("Could not parse cached {description}").into())
 }
 
-#[cfg(target_os = "macos")]
-fn macos_dark_mode_active() -> bool {
-    const PREFERENCES_FILE: &str = "Library/Preferences/.GlobalPreferences.plist";
-    const STYLE_KEY: &str = "AppleInterfaceStyle";
-
-    let preferences_file = home::home_dir()
-        .map(|home| home.join(PREFERENCES_FILE))
-        .expect("Could not get home directory");
-
-    match plist::Value::from_file(preferences_file).map(|file| file.into_dictionary()) {
-        Ok(Some(preferences)) => match preferences.get(STYLE_KEY).and_then(|val| val.as_string()) {
-            Some(value) => value == "Dark",
-            // If the key does not exist, then light theme is currently in use.
-            None => false,
-        },
-        // Unreachable, in theory. All macOS users have a home directory and preferences file setup.
-        Ok(None) | Err(_) => true,
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/src/bin/bat/app.rs b/src/bin/bat/app.rs
index c7262aa3..8f69870f 100644
--- a/src/bin/bat/app.rs
+++ b/src/bin/bat/app.rs
@@ -9,6 +9,7 @@ use crate::{
     config::{get_args_from_config_file, get_args_from_env_opts_var, get_args_from_env_vars},
 };
 use bat::style::StyleComponentList;
+use bat::theme::{theme, ThemeName, ThemeOptions, ThemePreference};
 use bat::BinaryBehavior;
 use bat::StripAnsiMode;
 use clap::ArgMatches;
@@ -17,7 +18,6 @@ use console::Term;
 
 use crate::input::{new_file_input, new_stdin_input};
 use bat::{
-    assets::HighlightingAssets,
     bat_warning,
     config::{Config, VisibleLines},
     error::*,
@@ -278,18 +278,7 @@ impl App {
                 Some("auto") => StripAnsiMode::Auto,
                 _ => unreachable!("other values for --strip-ansi are not allowed"),
             },
-            theme: self
-                .matches
-                .get_one::<String>("theme")
-                .map(String::from)
-                .map(|s| {
-                    if s == "default" {
-                        String::from(HighlightingAssets::default_theme())
-                    } else {
-                        s
-                    }
-                })
-                .unwrap_or_else(|| String::from(HighlightingAssets::default_theme())),
+            theme: theme(self.theme_options()).to_string(),
             visible_lines: match self.matches.try_contains_id("diff").unwrap_or_default()
                 && self.matches.get_flag("diff")
             {
@@ -448,4 +437,25 @@ impl App {
 
         Ok(styled_components)
     }
+
+    fn theme_options(&self) -> ThemeOptions {
+        let theme = self
+            .matches
+            .get_one::<String>("theme")
+            .map(|t| ThemePreference::from_str(t).unwrap())
+            .unwrap_or_default();
+        let theme_dark = self
+            .matches
+            .get_one::<String>("theme-dark")
+            .map(|t| ThemeName::from_str(t).unwrap());
+        let theme_light = self
+            .matches
+            .get_one::<String>("theme-light")
+            .map(|t| ThemeName::from_str(t).unwrap());
+        ThemeOptions {
+            theme,
+            theme_dark,
+            theme_light,
+        }
+    }
 }
diff --git a/src/bin/bat/clap_app.rs b/src/bin/bat/clap_app.rs
index ac1f4007..f5e3948e 100644
--- a/src/bin/bat/clap_app.rs
+++ b/src/bin/bat/clap_app.rs
@@ -393,10 +393,41 @@ pub fn build_app(interactive_output: bool) -> Command {
                      see all available themes. To set a default theme, add the \
                      '--theme=\"...\"' option to the configuration file or export the \
                      BAT_THEME environment variable (e.g.: export \
-                     BAT_THEME=\"...\").",
+                     BAT_THEME=\"...\").\n\n\
+                     Special values:\n\n  \
+                     * auto: Picks a dark or light theme depending on the terminal's colors (default).\n          \
+                     Use '--theme-light' and '--theme-dark' to customize the selected theme.\n    \
+                     * auto:always: Detect the terminal's colors even when the output is redirected.\n    \
+                     * auto:system: Detect the color scheme from the system-wide preference (macOS only).\n  \
+                     * dark: Use the dark theme specified by '--theme-dark'.\n  \
+                     * light: Use the light theme specified by '--theme-light'.",
                 ),
         )
         .arg(
+            Arg::new("theme-light")
+                .long("theme-light")
+                .overrides_with("theme-light")
+                .value_name("theme")
+                .help("Sets the color theme for syntax highlighting used for light backgrounds.")
+                .long_help(
+                    "Sets the theme name for syntax highlighting used when the terminal uses a light background. \
+                    Use '--list-themes' to see all available themes. To set a default theme, add the \
+                    '--theme-light=\"...\" option to the configuration file or export the BAT_THEME_LIGHT \
+                    environment variable (e.g. export BAT_THEME_LIGHT=\"...\")."),
+        )
+        .arg(
+            Arg::new("theme-dark")
+                .long("theme-dark")
+                .overrides_with("theme-dark")
+                .value_name("theme")
+                .help("Sets the color theme for syntax highlighting used for dark backgrounds.")
+                .long_help(
+                    "Sets the theme name for syntax highlighting used when the terminal uses a dark background. \
+                    Use '--list-themes' to see all available themes. To set a default theme, add the \
+                    '--theme-dark=\"...\" option to the configuration file or export the BAT_THEME_DARK \
+                    environment variable (e.g. export BAT_THEME_DARK=\"...\")."),
+        )
+        .arg(
             Arg::new("list-themes")
                 .long("list-themes")
                 .action(ArgAction::SetTrue)
diff --git a/src/bin/bat/config.rs b/src/bin/bat/config.rs
index 6fa18f09..a0ee7ba3 100644
--- a/src/bin/bat/config.rs
+++ b/src/bin/bat/config.rs
@@ -140,7 +140,9 @@ fn get_args_from_str(content: &str) -> Result<Vec<OsString>, shell_words::ParseE
 pub fn get_args_from_env_vars() -> Vec<OsString> {
     [
         ("--tabs", "BAT_TABS"),
-        ("--theme", "BAT_THEME"),
+        ("--theme", bat::theme::env::BAT_THEME),
+        ("--theme-dark", bat::theme::env::BAT_THEME_DARK),
+        ("--theme-light", bat::theme::env::BAT_THEME_LIGHT),
         ("--pager", "BAT_PAGER"),
         ("--paging", "BAT_PAGING"),
         ("--style", "BAT_STYLE"),
diff --git a/src/bin/bat/main.rs b/src/bin/bat/main.rs
index 3b74ec75..7b7bafe6 100644
--- a/src/bin/bat/main.rs
+++ b/src/bin/bat/main.rs
@@ -14,6 +14,7 @@ use std::io::{BufReader, Write};
 use std::path::Path;
 use std::process;
 
+use bat::theme::DetectColorScheme;
 use nu_ansi_term::Color::Green;
 use nu_ansi_term::Style;
 
@@ -30,12 +31,12 @@ use directories::PROJECT_DIRS;
 use globset::GlobMatcher;
 
 use bat::{
-    assets::HighlightingAssets,
     config::Config,
     controller::Controller,
     error::*,
     input::Input,
     style::{StyleComponent, StyleComponents},
+    theme::{color_scheme, default_theme, ColorScheme},
     MappingTarget, PagingMode,
 };
 
@@ -189,7 +190,12 @@ fn theme_preview_file<'a>() -> Input<'a> {
     Input::from_reader(Box::new(BufReader::new(THEME_PREVIEW_DATA)))
 }
 
-pub fn list_themes(cfg: &Config, config_dir: &Path, cache_dir: &Path) -> Result<()> {
+pub fn list_themes(
+    cfg: &Config,
+    config_dir: &Path,
+    cache_dir: &Path,
+    detect_color_scheme: DetectColorScheme,
+) -> Result<()> {
     let assets = assets_from_cache_or_binary(cfg.use_custom_assets, cache_dir)?;
     let mut config = cfg.clone();
     let mut style = HashSet::new();
@@ -200,10 +206,14 @@ pub fn list_themes(cfg: &Config, config_dir: &Path, cache_dir: &Path) -> Result<
     let stdout = io::stdout();
     let mut stdout = stdout.lock();
 
-    let default_theme = HighlightingAssets::default_theme();
+    let default_theme_name = default_theme(color_scheme(detect_color_scheme).unwrap_or_default());
     for theme in assets.themes() {
-        let default_theme_info = if !config.loop_through && default_theme == theme {
+        let default_theme_info = if !config.loop_through && default_theme_name == theme {
             " (default)"
+        } else if default_theme(ColorScheme::Dark) == theme {
+            " (default dark)"
+        } else if default_theme(ColorScheme::Light) == theme {
+            " (default light)"
         } else {
             ""
         };
@@ -371,7 +381,7 @@ fn run() -> Result<bool> {
                 };
                 run_controller(inputs, &plain_config, cache_dir)
             } else if app.matches.get_flag("list-themes") {
-                list_themes(&config, config_dir, cache_dir)?;
+                list_themes(&config, config_dir, cache_dir, DetectColorScheme::default())?;
                 Ok(true)
             } else if app.matches.get_flag("config-file") {
                 println!("{}", config_file().to_string_lossy());
diff --git a/src/lib.rs b/src/lib.rs
index a015913e..502427a7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -49,6 +49,7 @@ pub(crate) mod printer;
 pub mod style;
 pub(crate) mod syntax_mapping;
 mod terminal;
+pub mod theme;
 mod vscreen;
 pub(crate) mod wrapping;
 
diff --git a/src/pretty_printer.rs b/src/pretty_printer.rs
index eb123ea3..51c9af80 100644
--- a/src/pretty_printer.rs
+++ b/src/pretty_printer.rs
@@ -245,7 +245,9 @@ impl<'a> PrettyPrinter<'a> {
         self
     }
 
-    /// Specify the highlighting theme
+    /// Specify the highlighting theme.
+    /// You can use [`crate::theme::theme`] to pick a theme based on user preferences
+    /// and the terminal's background color.
     pub fn theme(&mut self, theme: impl AsRef<str>) -> &mut Self {
         self.config.theme = theme.as_ref().to_owned();
         self
diff --git a/src/theme.rs b/src/theme.rs
new file mode 100644
index 00000000..9fbef238
--- /dev/null
+++ b/src/theme.rs
@@ -0,0 +1,571 @@
+//! Utilities for choosing an appropriate theme for syntax highlighting.
+
+use std::convert::Infallible;
+use std::fmt;
+use std::io::IsTerminal as _;
+use std::str::FromStr;
+
+/// Environment variable names.
+pub mod env {
+    /// See [`crate::theme::ThemeOptions::theme`].
+    pub const BAT_THEME: &str = "BAT_THEME";
+    /// See [`crate::theme::ThemeOptions::theme_dark`].
+    pub const BAT_THEME_DARK: &str = "BAT_THEME";
+    /// See [`crate::theme::ThemeOptions::theme_light`].
+    pub const BAT_THEME_LIGHT: &str = "BAT_THEME";
+}
+
+/// Chooses an appropriate theme or falls back to a default theme
+/// based on the user-provided options and the color scheme of the terminal.
+///
+/// Intentionally returns a [`ThemeResult`] instead of a simple string so
+/// that downstream consumers such as `delta` can easily apply their own
+/// default theme and can use the detected color scheme elsewhere.
+pub fn theme(options: ThemeOptions) -> ThemeResult {
+    theme_impl(options, &TerminalColorSchemeDetector)
+}
+
+/// The default theme, suitable for the given color scheme.
+/// Use [`theme`] if you want to automatically detect the color scheme from the terminal.
+pub const fn default_theme(color_scheme: ColorScheme) -> &'static str {