function theme --description 'Switch kitty between its light and dark color themes'
    set -l config_dir (__kitty_config_dir)

    if test (count $argv) -gt 1
        echo "theme: expected at most one argument" >&2
        return 2
    end

    set -l target $argv[1]
    test -z "$target"
    and set target toggle

    switch $target
        case -h --help help
            printf '%s\n' \
                'Usage: theme [light|dark|auto|status]' \
                '' \
                '  theme         toggle between light and dark' \
                '  theme light   pin kitty to light' \
                '  theme dark    pin kitty to dark' \
                '  theme auto    follow the macOS appearance again' \
                '  theme status  print the current mode' \
                '' \
                'The mode is remembered in '(__kitty_config_dir)'/theme-mode and' \
                'applies to new kitty instances too.'
            return 0
        case status
            set -l setting (__kitty_theme_mode_setting)
            if test "$setting" = auto
                printf '%s (auto, following macOS)\n' (__kitty_theme_current)
            else
                printf '%s (pinned)\n' $setting
            end
            return 0
        case toggle
            if test (__kitty_theme_current) = dark
                set target light
            else
                set target dark
            end
            # Nothing to pin when the result already matches macOS -- record
            # `auto` so kitty keeps following the OS from here on.
            test "$target" = (__kitty_macos_appearance)
            and set target auto
        case auto light dark
            # handled below
        case '*'
            echo "theme: unknown mode '$target' (expected light, dark, auto or status)" >&2
            return 2
    end

    set -l apply "$HOME/.config/kitty/apply-theme-mode.sh"
    if not test -x $apply
        echo "theme: missing $apply" >&2
        return 1
    end

    echo $target >$config_dir/theme-mode
    or return $status

    $apply "$config_dir"
    or return $status

    # Reloading is what makes kitty pick up the regenerated theme files.
    if set -q KITTY_WINDOW_ID
        kitty @ load-config
        or return $status
    end

    set -l effective (__kitty_theme_current)

    if functions -q __tide_apply_terminal_appearance
        __tide_apply_terminal_appearance $effective
        set -l apply_status $status
        if test $apply_status -eq 0
            functions -q _tide_cache_variables
            and _tide_cache_variables
            functions -q _tide_sub_reload
            and tide reload
        end
    end

    if test "$target" = auto
        printf '%s (auto, following macOS)\n' $effective
    else
        printf '%s (pinned)\n' $effective
    end
end