jakehilborn/displayplacer
Displayplacer
Displayplacer is a command-line tool for managing multi-monitor display layouts on macOS. It enables users to save, apply, and automate screen configurations including resolution, rotation, arrangement, and mirroring settings entirely from the terminal without requiring a graphical interface.
The tool identifies displays using persistent hardware IDs rather than port-based identifiers, allowing layouts to be restored consistently across reconnections and reboots. It supports headless display configuration, enabling or disabling monitors, rotating internal and external displays, and designating a primary screen. Mirroring setups are handled with automatic resolution optimization for the primary display in a mirrored group.
Displayplacer encodes full multi-monitor parameters into compact string arguments for easy saving and replaying of layouts. It can list current screen configurations as command-line arguments for creating reusable profiles, and applies only valid configurations by matching requested settings against supported hardware modes. The tool also provides session-aware identifier fallback for maintaining layout stability when macOS reassigns hardware IDs.
Features
- Persistent Layout Automators - Programmatically saving and applying screen layouts with persistent hardware identifiers for consistent multi-monitor setups.
- Layout Tools - Utility for saving and applying persistent monitor arrangements across multiple displays.
- macOS Display Layout Managers - Command-line tool for managing screen resolutions, refresh rates, and monitor layouts on macOS.
- Display Configuration Managers - Lists all connected displays with their current resolution, position, and mirroring settings for inspection.
- Internal Display Rotators - Changes the rotation of a built-in MacBook screen by specifying a degree value (0, 90, 180, or 270).
- Display Identifiers - Uses stable or session-specific screen identifiers to handle layout changes when macOS reassigns IDs.
- Screen Configuration Listers - Displays current screen identifiers, resolutions, and arrangement details for all connected monitors.
- Hardware Mode Filtering - Matches requested display settings against the set of supported hardware modes to apply only valid configurations.
- CLI Configurators - Program for setting display scaling, rotation, and mirroring settings from the terminal.
- Display Fallback Identifiers - Uses contextual session identifiers when persistent hardware IDs are reassigned by macOS, maintaining layout stability across reboots.
- Hardware Configuration Persistence - Links display configurations to stable hardware IDs instead of port-based identifiers for consistent layout restoration across reconnections.
- Command-Line Display Configurators - Manages display layouts entirely through command-line arguments without requiring a graphical user interface or window server interaction.
- Display Layout Managers - Managing the arrangement, resolution, and rotation of multiple displays on macOS through command-line automation.
- Display Layout Appliers - Sets each display's resolution, arrangement, and mirroring state from a saved or constructed configuration string.
- Primary Display Designators - Designates the screen at origin (0,0) as the primary display, equivalent to dragging the white bar in System Preferences.
- Multi-Monitor Layout Configurators - Sets resolution, rotation, arrangement, and mirroring for each display using a compact string argument.
- Screen Layout Appliers - Sets resolution, rotation, position, mirroring, and enabled state for each display using a compact configuration string.
- Degree-Based Rotators - Changing the rotation of internal and external displays on macOS by specifying degree values.
- macOS Screen Mirroring Configurators - Configuring multiple displays to mirror content with automatic resolution optimization for the primary screen.
- Multi-Monitor Mirroring Configurators - Groups multiple screens into a mirrored set, designating the first screen as the primary for resolution optimization.
- Display Mirroring Optimizers - Designates the first display in a mirrored set as primary and optimizes resolution across grouped screens for consistent output.
- Display Configuration Inspectors - Prints the current display layout, resolutions, and rotation settings as command-line arguments for creating reusable profiles.
- Headless Display Configurators - Enabling or disabling monitors and configuring display settings without a graphical user interface on macOS.
- Display Enablers - Turns off a specific screen by setting its enabled state to false, with re-enable support via unplug/replug or command.
