{"id":17271972,"url":"https://github.com/pndurette/zsh-lux","last_synced_at":"2025-04-14T08:40:23.320Z","repository":{"id":76741354,"uuid":"175132467","full_name":"pndurette/zsh-lux","owner":"pndurette","description":"zsh plugin to toggle light/dark modes of macOS but also of iTerm, Visual Studio Code and anything you can script/theme","archived":false,"fork":false,"pushed_at":"2024-01-21T02:12:40.000Z","size":30,"stargazers_count":34,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T08:11:18.262Z","etag":null,"topics":["dark-mode","macos","terminal","zsh","zsh-plugin"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pndurette.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-12T04:00:30.000Z","updated_at":"2025-01-29T10:35:06.000Z","dependencies_parsed_at":"2023-10-03T07:49:36.154Z","dependency_job_id":"bb94675b-4c88-4c51-a0a2-2dff783a2250","html_url":"https://github.com/pndurette/zsh-lux","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pndurette%2Fzsh-lux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pndurette%2Fzsh-lux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pndurette%2Fzsh-lux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pndurette%2Fzsh-lux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pndurette","download_url":"https://codeload.github.com/pndurette/zsh-lux/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248848494,"owners_count":21171387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dark-mode","macos","terminal","zsh","zsh-plugin"],"created_at":"2024-10-15T08:47:29.123Z","updated_at":"2025-04-14T08:40:23.297Z","avatar_url":"https://github.com/pndurette.png","language":"Shell","funding_links":[],"categories":["Plugins"],"sub_categories":["ZSH on Windows","Zinit (née zplugin)"],"readme":"# zsh-lux\n\n**zsh-lux**, a zsh plugin to toggle the light \u0026 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.\n\nAlso 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.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Demo\n\n![Imgur](https://i.imgur.com/r5F5aSB.gif)\n\n## Documentation\n\n* [Installation](#installation)\n   * [Usage](#usage)\n       * [lux](#lux)\n       * [macos_is_dark](#macos_is_dark)\n       * [macos_release_name](#macos_release_name)\n       * [Debug mode](#debug-mode)\n   * [Items](#items)\n       * [macos](#macos)\n       * [macos_desktop](#macos_desktop)\n       * [macos_desktop_style](#macos_desktop_style)\n       * [iterm](#iterm)\n       * [iterm_all](#iterm_all)\n       * [vscode](#vscode)\n       * [all](#all)\n   * [Extending zsh-lux](#extending-zsh-lux)\n       * [Adding items](#adding-items)\n       * [Adding modes](#adding-modes)\n   * [Caveats / known issues](#caveats--known-issues)\n       * [macOS Sonoma (14)](#macos-sonoma-14)\n\n### Installation\n\n**[Antigen](https://github.com/zsh-users/antigen)**\n\n```bash\nantigen bundle pndurette/zsh-lux   # in your ~/.zshrc\n```\n\n**[Antibody](https://github.com/getantibody/antibody)**\n\n```bash\nantibody bundle pndurette/zsh-lux   # in your ~/.zshrc\n```\n\n**[Oh My Zsh](https://github.com/robbyrussell/oh-my-zsh)**\n\n```bash\ncd ~/.oh-my-zsh/custom/plugins/\ngit clone https://github.com/pndurette/zsh-lux.git\n```\n\n```bash\nplugins=( ... zsh-lux )   # in your ~/.zshrc\n```\n\n**[Zplug](https://github.com/zplug/zplug)**\n\n```bash\nzplug \"pndurette/zsh-lux\"   # in your ~/.zshrc\n```\n\n**Manual Install**\n\n```bash\ngit clone https://github.com/pndurette/zsh-lux.git\ncd zsh-lux \u0026\u0026 source ./zsh-lux.plugin.zsh\n```\n\n```bash\nfpath=(/your/zsh-lux/directory/ $fpath)    # (before compinit) load shell completion\n```\n\n\n### Usage\n\n#### `lux`\n\nSwitch to/activate the mode (i.e `light`, `dark`) of macOS or of another item.\n\n`lux \u003citem\u003e \u003cmode\u003e` \n\nExample usage:\n\n```bash\nlux macos dark\nlux macos light\nlux iterm light\n# ...\n```\n\n#### `macos_is_dark`\n\nHelper function that checks if the dark mode in macOS is active.\n\n* Returns:\n  * `0` if dark mode is active\n  * `1` if light mode is active\n  * `2` if the status of the dark mode can't be determined (i.e. the version of macOS does not support it)\n\nExample usage:\n\n```bash\nif macos_is_dark; then\n    echo \"macOS is dark!\"\nelse\n    echo \"macOS is light!\"\nfi\n```\n\n#### `macos_release_name`\n\nHelper function that returns the capitalized release name of macOS (e.g. \"Monterey\")\n\nExample usage:\n\n```bash\n$ sw_vers -productVersion\n12.6\n$ macos_release_name\nMonterey\n```\n\n#### Debug mode\n\nSet `LUX_DEBUG=1` to get a log output for debuging purposes.\n\n### Items\n\nAn 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_\u003cITEM\u003e_\u003cMODE\u003e`. In most cases, these variables can be redefined (e.g. in `.zshrc`).\n\n#### `macos`\n\n**Action**: Sets macOS dark mode\n\n**Requires**: macOS\n\n**Modes**:\n\n| Mode    | Variable          | Default | Customizable |\n| ------- | ----------------- | ------- | ------------ |\n| `light` | `LUX_MACOS_LIGHT` | `false` | 🚫            |\n| `dark`  | `LUX_MACOS_DARK`  | `true`  | 🚫            |\n\n**Extra configuration**: N/A\n\n---\n\n#### `macos_desktop`\n\n**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](https://support.apple.com/en-ca/guide/mac-help/mchlp3013/12.0/mac/12.0). For those desktop pictures, set the same path for both `light` and `dark` and use [macos_desktop_style](#macos_desktop_style) to choose the appearance setting.\n\n*Note:* Only the `\u003cmacOS name\u003e 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/`\n\n**Requires**: macOS\n\n**Modes**:\n\n| Mode    | Variable                  | Default                                                      | Customizable |\n| ------- | ------------------------- | ------------------------------------------------------------ | ------------ |\n| `light` | `LUX_MACOS_DESKTOP_LIGHT` | `/System/Library/Desktop Pictures/\u003cmacOS name\u003e Graphic.heic` | ✅            |\n| `dark`  | `LUX_MACOS_DESKTOP_DARK`  | ``/System/Library/Desktop Pictures/\u003cmacOS name\u003e Graphic.heic`` | ✅            |\n\n**Extra configuration**: N/A\n\n---\n\n#### `macos_desktop_style`\n\n**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).\n\n**Requires**: macOS\n\n**Modes**:\n\n| Mode      | Variable                          | Default   | Customizable |\n| --------- | --------------------------------- | --------- | ------------ |\n| `light`   | `LUX_MACOS_DESKTOP_STYLE_LIGHT`   | `light`   | 🚫            |\n| `dark`    | `LUX_MACOS_DESKTOP_STYLE_DARK`    | `dark`    | 🚫            |\n| `auto`    | `LUX_MACOS_DESKTOP_STYLE_AUTO`    | `auto`    | 🚫            |\n| `dynamic` | `LUX_MACOS_DESKTOP_STYLE_DYNAMIC` | `dynamic` | 🚫            |\n\n**Extra configuration**: N/A\n\n------\n\n#### `iterm`\n\n**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.\n\n**Requires**: macOS, [iTerm2](https://iterm2.com)\n\n**Modes**:\n\n| Mode    | Variable          | Default           | Customizable |\n| ------- | ----------------- | ----------------- | ------------ |\n| `light` | `LUX_ITERM_LIGHT` | `Solarized Light` | ✅            |\n| `dark`  | `LUX_ITERM_DARK`  | `Solarized Dark`  | ✅            |\n\n**Extra configuration**: N/A\n\n------\n\n#### `iterm_all`\n\n**Action**:  Same as [`iterm`](#iterm) but for all open sessions.\n\n**Requires**: macOS, [iTerm2](https://iterm2.com)\n\n**Modes**:\n\n| Mode    | Variable              | Default           | Customizable |\n| ------- | --------------------- | ----------------- | ------------ |\n| `light` | `LUX_ITERM_ALL_LIGHT` | `Solarized Light` | ✅            |\n| `dark`  | `LUX_ITERM_ALL_DARK`  | `Solarized Dark`  | ✅            |\n\n**Extra configuration**: N/A\n\n------\n\n#### `vscode`\n\n**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.\n\n**Requires**: [Visual Studio Code](https://code.visualstudio.com), [jq](https://stedolan.github.io/jq/)\n\n**Modes**:\n\n| Mode    | Variable           | Default           | Customizable |\n| ------- | ------------------ | ----------------- | ------------ |\n| `light` | `LUX_VSCODE_LIGHT` | `Solarized Light` | ✅            |\n| `dark`  | `LUX_VSCODE_DARK`  | `Solarized Dark`  | ✅            |\n\n**Extra configuration**:\n\n| Setting                                   | Variable                   | Default                                                     | Customizable |\n| ----------------------------------------- | -------------------------- | ----------------------------------------------------------- | ------------ |\n| Location of the `settings.json` user file | `LUX_VSCODE_USER_SETTINGS` | `$HOME/Library/Application Support/Code/User/settings.json` | ✅            |\n\n------\n\n#### `all`\n\n**Action**:  Sets all items to the same mode at once. Under the hood, this calls `lux` on each item of a list.\n\n**Requires**: Any requirements of the referenced items.\n\n**Modes**:\n\n| Mode    | Variable        | Default | Customizable |\n| ------- | --------------- | ------- | ------------ |\n| `light` | `LUX_ALL_LIGHT` | `light` | 🚫            |\n| `dark`  | `LUX_ALL_DARK`  | `dark`  | 🚫            |\n\n**Extra configuration**:\n\n| Setting                              | Variable       | Default                                                      | Customizable |\n| ------------------------------------ | -------------- | :----------------------------------------------------------- | ------------ |\n| Array of the items affected by `all` | `LUX_ALL_LIST` | `( macos macos_desktop macos_desktop_style iterm_all vscode )` | ✅            |\n\n------\n\n### Extending `zsh-lux`\n\n`zsh-lux` is convention-based and can therefore be easily expanded. See the plugin file for examples.\n\n#### Adding items\n\nBetter 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*':\n\n1. Define a function named `_lux_set_\u003citem\u003e`  that sets theme name in `/tmp/wow.cfg` from an argument `$1`:\n\n   ```bash\n   function _lux_set_wow() {\n     echo \"$1\" \u003e /tmp/wow.cfg\n   }\n   ```\n\n2. Define `LUX_\u003cITEM\u003e_\u003cMODE\u003e` for the modes:\n\n   ```bash\n   LUX_WOW_LIGHT='white'\n   LUX_WOW_DARK='black'\n   ```\n\n**Done!** Now just call:\n\n```bash\nlux wow light # or\nlux wow dark\n```\n\nThis new item will also be automatically be added to zsh's tab autocompletion.\n\n#### Adding modes\n\nBy default, items have a `light` and `dark` mode, but adding other modes is a simple as defining a new variable.\n\nFor example to add the modes `superhero` (that sets the [`batman`](https://github.com/mbadolato/iTerm2-Color-Schemes#batman) iTerm colour scheme) and `purple` (that sets the [`c64`](https://github.com/mbadolato/iTerm2-Color-Schemes#c64) iTerm2 colour scheme), define `LUX_\u003cITEM\u003e_\u003cMODE\u003e` for each:\n\n```bash\nLUX_ITERM_SUPERHERO=\"batman\"\nLUX_ITERM_PURPLE=\"c64\"\n```\n**Done!** Now just call:\n\n```bash\nlux iterm superhero\nlux iterm purple\n```\n*(Optional)* To add those extra modes to the tab autocompletion, define the `LUX_\u003cITEM\u003e_EXTRAS` variable with space-delimited values of those extra modes:\n\n```bash\nLUX_ITERM_EXTRAS=\"superhero purple\"\n```\n\n### Caveats / known issues\n\n#### macOS Sonoma (14)\n\n* 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).\n\n  (This is the case of `System/Library/Desktop Pictures/Sonoma.heic` which is the default used by `macos_desktop` when on Sonoma.)\n\n  **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.\n\n  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 )`\n\n## Fun aliases!\n\n```bash\nalias lumos='lux all light'\nalias nox='lux all dark'\n```\n\n## License\n\n[The MIT License (MIT)](LICENSE) Copyright © 2019-2024 Pierre Nicolas Durette\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpndurette%2Fzsh-lux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpndurette%2Fzsh-lux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpndurette%2Fzsh-lux/lists"}