MagicDisplay is an early macOS command line tool for inspecting and applying display layouts. Save your preferred setup as a named profile or retained layout, then restore it predictably from a shell command — or let a LaunchAgent apply it automatically.
macOS ties display arrangements to specific monitor identities and setups. Swapping between home, office, and travel monitors means rearranging windows in System Settings, over and over. MagicDisplay makes a consistent layout reproducible and automatable.
magicdisplay list shows the full current display state, and a displayplacer-compatible apply path replays a complete layout from a single shell command.
Save a setup once with profile save home, then recall it by name. Profiles store resolution, refresh rate, scaling, position, rotation, mirroring, and enabled state in human-readable files.
profile apply --dry-run and layout preview show exactly what would change without mutating a single display.
Define a preferred relative position — above, right, left, or below an anchor display — and MagicDisplay places any connected external monitor there, even ones it has never seen before.
A macOS LaunchAgent watches for display topology changes, waits for the setup to settle, and applies your retained layout automatically — with notifications and a bounded retry model.
Profiles record persistent, serial, and contextual display IDs so layouts keep working when macOS reassigns a screen id after a dock, cable, or GPU switch. profile remap fixes a profile in one command.
MagicDisplay is built for macOS. No installer package is currently published; build from source with Xcode command line tools.
# Build from source on macOS cd src make # Run the built CLI src/magicdisplay list
displayplacer project. Expect the CLI to stay close to the upstream baseline while MagicDisplay-specific features land.
# Save your current home setup, then apply it later magicdisplay profile save home magicdisplay profile apply home # Keep any external monitor above your laptop, automatically magicdisplay layout set position:above magicdisplay agent install
See the documentation for the full command reference, storage details, and automation safety contract.