Discover, install, and configure shell plugins with Fig Plugin Store β†’

Zsh Lux

zsh plugin to toggle light/dark modes of macOS but also of iTerm, Visual Studio Code and anything you can script/theme

28 stars
2 forks


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.

License: MIT






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


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

Oh My Zsh

cd ~/.oh-my-zsh/custom/plugins/
git clone
plugins=( ... zsh-lux )   # in your ~/.zshrc


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

Manual Install

git clone
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!"
    echo "macOS is light!"

Debug mode

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


Mode Variable Default Customizable
light LUX_MACOS_LIGHT false 🚫
dark LUX_MACOS_DARK true 🚫

Extra configuration: N/A


Action: Sets macOS desktop picture

Requires: macOS


Mode Variable Default Customizable
light LUX_MACOS_DESKTOP_LIGHT /Library/Desktop Pictures/Mojave Day.jpg βœ…
dark LUX_MACOS_DESKTOP_DARK /Library/Desktop Pictures/Mojave Night.jpg βœ…

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 for examples.

Requires: macOS, iTerm2


Mode Variable Default Customizable
light LUX_ITERM_LIGHT Solarized Light βœ…
dark LUX_ITERM_DARK Solarized Dark βœ…

Extra configuration: N/A


Action: Same as iterm but for all open sessions.

Requires: macOS, iTerm2


Mode Variable Default Customizable
light LUX_ITERM_ALL_LIGHT Solarized Light βœ…
dark LUX_ITERM_ALL_DARK Solarized Dark βœ…

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


Mode Variable Default Customizable
light LUX_VSCODE_LIGHT Solarized Light βœ…
dark LUX_VSCODE_DARK Solarized Dark βœ…

Extra configuration:

Setting Variable Default Customizable
Location of the settings.json user file LUX_VSCODE_USER_SETTINGS $HOME/Library/Application Support/Code/User/settings.json βœ…


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.


Mode Variable Default Customizable
light LUX_ALL_LIGHT light 🚫
dark LUX_ALL_DARK dark 🚫

Extra configuration:

Setting Variable Default Customizable
Array of the items affected by all LUX_ALL_LIST ( macos macos_desktop iterm_all vscode ) βœ…

Extending zsh-lux

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

Adding items

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
  1. Define LUX_<ITEM>_<MODE> for the modes:

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.

Adding modes

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:


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"

Fun aliases!

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


The MIT License (MIT) Copyright Β© 2019 Pierre Nicolas Durette