zsh-lux, a zsh plugin to toggle the light & dark modes of macOS and other items and applications via the lux command. Highly customizable: included items can be configured by defining variables. Highly extensible: items can be added by defining functions.

Also features the macos_is_dark helper function to determine if the macOS dark mode (in 10.14 ) is active, for example to handle terminal theming.

• Installation
  • Usage
    • lux
    • macos_is_dark
    • macos_release_name
    • Debug mode
  • Items
    • macos
    • macos_desktop
    • macos_desktop_style
    • iterm
    • iterm_all
    • vscode
    • all
  • Extending zsh-lux
    • Adding items
    • Adding modes
  • Caveats / known issues
    • macOS Sonoma (14)

Antigen

antigen bundle pndurette/zsh-lux   # in your ~/.zshrc

Antibody

antibody bundle pndurette/zsh-lux   # in your ~/.zshrc

Oh My Zsh

cd ~/.oh-my-zsh/custom/plugins/
git clone https://github.com/pndurette/zsh-lux.git

plugins=( ... zsh-lux )   # in your ~/.zshrc

Zplug

zplug "pndurette/zsh-lux"   # in your ~/.zshrc

Manual Install

git clone https://github.com/pndurette/zsh-lux.git
cd zsh-lux && source ./zsh-lux.plugin.zsh

fpath=(/your/zsh-lux/directory/ $fpath)    # (before compinit) load shell completion

Switch to/activate the mode (i.e light, dark) of macOS or of another item.

lux <item> <mode>

Example usage:

lux macos dark
lux macos light
lux iterm light
# ...

Helper function that checks if the dark mode in macOS is active.

• Returns:
  • 0 if dark mode is active
  • 1 if light mode is active
  • 2 if the status of the dark mode can't be determined (i.e. the version of macOS does not support it)

Example usage:

if macos_is_dark; then
    echo "macOS is dark!"
else
    echo "macOS is light!"
fi

Helper function that returns the capitalized release name of macOS (e.g. "Monterey")

Example usage:

$ sw_vers -productVersion
12.6
$ macos_release_name
Monterey

Set LUX_DEBUG=1 to get a log output for debuging purposes.

An item is represented by one function that can trigger an appearance change for that item. These functions take an argument (e.g. the name of a theme) which are retrieved from a variable which name's depends on the chosen mode (i.e. light, dark). These variables follow the convention LUX_<ITEM>_<MODE>. In most cases, these variables can be redefined (e.g. in .zshrc).

Action: Sets macOS dark mode

Requires: macOS

Modes:

Extra configuration: N/A

Action: Sets macOS desktop picture. On Mojave and above, Dynamic and Light and Dark Desktop pictures are special .heic files that contain multiple images that macOS can automatically change throughout the day. For those desktop pictures, set the same path for both light and dark and use macos_desktop_style to choose the appearance setting.

Note: Only the <macOS name> Graphic.heic (e.g. Ventura Graphic.heic) Dynamic Desktop comes pre-installed. To use other images than the default (below), select the image in System Preferences which will download it to ~/Library/Application Support/com.apple.mobileAssetDesktop/

Requires: macOS

Modes:

Extra configuration: N/A

Action: Sets macOS desktop picture style, for certain .heic images (in Mojave and above) that support it. Supported image types are either "Dynamic Desktop" (dynamic, image changes throughout the day) or "Light and Dark" (auto, image matches the macOS apperance). Either types can be expliclty set to their light or dark setting).

Requires: macOS

Modes:

Extra configuration: N/A

Action: Sets the current iTerm2 session's color to a preset name (the equivalent of ⌘-i → Colors → Color Presets… ). It does not affect profiles or preferences. Creating/importing/naming colour schemes is left to the user. See https://github.com/mbadolato/iTerm2-Color-Schemes for examples.

Requires: macOS, iTerm2

Modes:

Extra configuration: N/A

Action: Same as iterm but for all open sessions.

Requires: macOS, iTerm2

Modes:

Extra configuration: N/A

Action: Sets Visual Studio Code color theme. Modifies the workbench.colorTheme setting in the settings.json user file. Visual Studio Code applies settings as they are changed.

Requires: Visual Studio Code, jq

Modes:

Extra configuration:

Action: Sets all items to the same mode at once. Under the hood, this calls lux on each item of a list.

Requires: Any requirements of the referenced items.

Modes:

Extra configuration:

zsh-lux is convention-based and can therefore be easily expanded. See the plugin file for examples.

Better explained with an example: let's pretend we want to add an item for an application called 'wow' that reads its theme name in /tmp/wow.cfg. 'wow' is in light mode when the theme is 'white' and in dark mode when the theme is 'black':

1. Define a function named _lux_set_<item> that sets theme name in /tmp/wow.cfg from an argument $1:

   function _lux_set_wow() {
     echo "$1" > /tmp/wow.cfg
   }

2. Define LUX_<ITEM>_<MODE> for the modes:

   LUX_WOW_LIGHT='white'
   LUX_WOW_DARK='black'

Done! Now just call:

lux wow light # or
lux wow dark

This new item will also be automatically be added to zsh's tab autocompletion.

By default, items have a light and dark mode, but adding other modes is a simple as defining a new variable.

For example to add the modes superhero (that sets the batman iTerm colour scheme) and purple (that sets the c64 iTerm2 colour scheme), define LUX_<ITEM>_<MODE> for each:

LUX_ITERM_SUPERHERO="batman"
LUX_ITERM_PURPLE="c64"

Done! Now just call:

lux iterm superhero
lux iterm purple

(Optional) To add those extra modes to the tab autocompletion, define the LUX_<ITEM>_EXTRAS variable with space-delimited values of those extra modes:

LUX_ITERM_EXTRAS="superhero purple"

• Using certain HEIF images as desktop picture will cause macos_desktop_style to sometimes reset the desktop picture to the system default, Sonoma Horizons (the vineyard photo).

  (This is the case of System/Library/Desktop Pictures/Sonoma.heic which is the default used by macos_desktop when on Sonoma.)

  Workaround: Don't use macos_desktop_style with these images. When setting Sonoma.heic or any other troublesome image, the image acts as if macos_desktop_style was set to auto , i.e. the light/dark of the image will follow the system appearance.

  To use the all item, override the LUX_ALL_LIST in your shell config to skip macos_desktop_style , e.g. LUX_ALL_LIST=( macos macos_desktop iterm_all vscode )

alias lumos='lux all light'
alias nox='lux all dark'

The MIT License (MIT) Copyright © 2019-2024 Pierre Nicolas Durette