Documentation

Everything you need to control your displays with Lumino — from the menu bar or the terminal.

Getting Started

Install via Homebrew

The recommended way to install Lumino on macOS:

brew tap unit313/tap
brew install --cask lumino

Download directly

Alternatively, download the latest .zip from the homepage, unzip, and drag Lumino to your Applications folder.

First launch

Open Lumino from Applications. It appears as a sun icon in your menu bar. On first launch, macOS may ask you to grant Accessibility permissions — this is required for display control and keyboard shortcuts.

Menu Bar App

Click the Lumino icon in your menu bar to open the control panel. You'll see all connected displays with their controls.

Display controls

• Brightness — Drag the slider or use keyboard shortcuts. Built-in displays use the native API; external monitors use DDC/CI for hardware-level control.
• Volume — Adjust monitor speaker volume directly via DDC/CI (external monitors only).
• Contrast — Fine-tune contrast on external monitors.
• Input source — Switch monitor inputs (HDMI, DisplayPort, USB-C) without touching the monitor's OSD.

Built-in display toggle

Turn your MacBook's built-in display on or off instantly — use only your external monitor without closing the lid. Lumino uses a hardware-level API when available, with a soft-disable fallback (brightness 0 + dark overlay).

Night Shift for external monitors

Schedule warm color temperature on external monitors, just like the built-in Night Shift. Set a color temperature between 2700K (warm) and 6500K (daylight).

Display presets

Save your current display configuration (brightness, contrast, volume for all monitors) as a preset. Restore it with one click or a keyboard shortcut.

Keyboard Shortcuts

Lumino registers global keyboard shortcuts that work system-wide. Default shortcuts:

With PRO, you can customize all shortcuts and add new ones from the Preferences panel.

Pro Features

Lumino is free for essential display control. Lumino Pro ($9.99 one-time) unlocks:

• Multi-monitor DDC control — Full control over all connected external displays, not just one.
• Brightness sync — Automatically synchronize brightness across displays (match, proportional, or offset modes).
• Night Shift for externals — Scheduled color temperature for external monitors.
• App profiles — Auto-switch brightness and settings when specific apps activate.
• Display presets — Save and restore multi-display configurations.
• Custom keyboard shortcuts — Record any key combination for any action.
• XDR brightness — Push MacBook Pro beyond 500 nits for HDR content.
• Ambient light auto-adjust — Use the Mac's light sensor to adjust external monitors automatically.
• Dashboard widget — Quick-glance display status on your desktop.
• Media key intercept — Use your keyboard brightness keys to control external monitors.

CLI Reference

The lumino command-line tool gives you full display control from the terminal. It's installed automatically alongside the app.

Global flags

• --json Output as machine-readable JSON. Available on all commands.
• -d, --display <ID> Target a specific display by ID. Defaults to first external display if omitted.

list

# Human-readable
$ lumino list
1  Built-in   3456x2234
2  External   3840x2160  Dell U2723QE

# JSON output
$ lumino list --json

status

$ lumino
$ lumino status
$ lumino status --json

brightness

# Read brightness
$ lumino brightness
$ lumino brightness -d 2

# Set brightness
$ lumino brightness 75
$ lumino brightness 0.8 -d 1

# JSON
$ lumino brightness --json

contrast

$ lumino contrast
$ lumino contrast 50 -d 2

volume

$ lumino volume
$ lumino volume 30 -d 2

input

# Read current input
$ lumino input -d 2

# Switch to DisplayPort
$ lumino input 15 -d 2

# Switch to HDMI
$ lumino input 17 -d 2

power

# Read power state
$ lumino power -d 2

# Turn off external monitor
$ lumino power off -d 2

# Wake it back up
$ lumino power on -d 2

toggle-builtin

# Toggle
$ lumino toggle-builtin

# Explicit
$ lumino toggle-builtin off
$ lumino toggle-builtin on

color-temp

# Warm (Night Shift style)
$ lumino color-temp 2700

# Neutral white
$ lumino color-temp 4000

# Daylight (reset)
$ lumino color-temp 6500

# Specific display
$ lumino color-temp 3200 -d 2

Scripting Examples

Combine the lumino CLI with shell scripts, cron jobs, or automation tools for powerful display workflows.

Dim all displays at night

#!/bin/bash
# Add to crontab: 0 22 * * * ~/scripts/night-mode.sh
lumino brightness 30
lumino color-temp 2700
echo "Night mode enabled"

Morning reset

#!/bin/bash
# Add to crontab: 0 7 * * * ~/scripts/morning-reset.sh
lumino brightness 80
lumino color-temp 6500
echo "Displays reset for daytime"

Switch external monitor to HDMI when docked

#!/bin/bash
DISPLAY_ID=2
lumino input 17 -d $DISPLAY_ID
lumino brightness 70 -d $DISPLAY_ID
lumino volume 25 -d $DISPLAY_ID

JSON output for integration

# Get all display info as JSON
$ lumino list --json

# Parse with jq
$ lumino brightness --json | jq '.brightness'

# Use in scripts
BRIGHTNESS=$(lumino brightness --json -d 2 | jq '.brightness')
if [ "$BRIGHTNESS" -lt 20 ]; then
    echo "Display is very dim"
fi

Turn off built-in when external connected

#!/bin/bash
EXTERNAL_COUNT=$(lumino list --json | jq '[.[] | select(.isBuiltIn == false)] | length')
if [ "$EXTERNAL_COUNT" -gt 0 ]; then
    lumino toggle-builtin off
    echo "Built-in display disabled — using external only"
fi