Repository files navigation

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

Also features themacos_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.gitcd zsh-lux&&source ./zsh-lux.plugin.zsh

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

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

lux <item> <mode>

Example usage:

lux macos darklux macos lightlux 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;thenecho"macOS is dark!"elseecho"macOS is light!"fi

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

Example usage:

$ sw_vers -productVersion12.6$ macos_release_nameMonterey

SetLUX_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 conventionLUX_<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 andLight and Dark Desktop pictures are special.heic files that contain multiple images that macOS canautomatically change throughout the day. For those desktop pictures, set the same path for bothlight anddark and usemacos_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 picturestyle, 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 theirlight ordark setting).

Requires: macOS

Modes:

Extra configuration: N/A

Action: Sets thecurrent iTerm2 session's color to apreset 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. Seehttps://github.com/mbadolato/iTerm2-Color-Schemes for examples.

Requires: macOS,iTerm2

Modes:

Extra configuration: N/A

Action: Same asiterm but for all open sessions.

Requires: macOS,iTerm2

Modes:

Extra configuration: N/A

Action: Sets Visual Studio Code color theme. Modifies theworkbench.colorTheme setting in thesettings.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 callslux 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. DefineLUX_<ITEM>_<MODE> for the modes:

   LUX_WOW_LIGHT='white'LUX_WOW_DARK='black'

Done! Now just call:

lux wow light# orlux wow dark

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

By default, items have alight anddark mode, but adding other modes is a simple as defining a new variable.

For example to add the modessuperhero (that sets thebatman iTerm colour scheme) andpurple (that sets thec64 iTerm2 colour scheme), defineLUX_<ITEM>_<MODE> for each:

LUX_ITERM_SUPERHERO="batman"LUX_ITERM_PURPLE="c64"

Done! Now just call:

lux iterm superherolux iterm purple

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

LUX_ITERM_EXTRAS="superhero purple"

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

  (This is the case ofSystem/Library/Desktop Pictures/Sonoma.heic which is the default used bymacos_desktop when on Sonoma.)

  Workaround: Don't usemacos_desktop_style with these images. When settingSonoma.heic or any other troublesome image, the image acts as ifmacos_desktop_style was set toauto , i.e. the light/dark of the image will follow the system appearance.

  To use theall item, override theLUX_ALL_LIST in your shell config to skipmacos_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