CLI reference | MoreDisplays

mdctl is a small tool with 10 commands. It does not manage displays itself: it opens a unix socket, hands one request to the running app, prints the reply and exits.

That is the whole design. Everything that decides anything lives in the app, so the tool cannot disagree with the window about what a group is.

Every command

Looking around

None of these change anything. Safe to run from a monitoring loop.

status	Print the app version, the engine state and the group list.
list	Print every group name, one per line.
displays	Print the displays the machine is showing.
edid	Print what one display says about itself.

Switching

The reason the tool exists: change the whole machine from a shell.

activate	Switch the machine to a group.
deactivate	Tear the active group down.

Writing back

Take the arrangement the machine is in and put it into a group.

capture	Capture the live layout into a group.

The tool itself

Neither needs a running app.

help	Print the usage text.
docs	Print this description of the tool, as JSON.

There is also a single page containing every command, and a recipes page with complete scripts rather than individual commands.

How it reaches the app

The tool connects to a unix domain socket in the support directory. Nothing listens on a network port, and nothing privileged is involved: the socket belongs to the app, running as you, and only a process running as you can open it.

$ ls -l ~/Library/Application Support/MoreDisplays/mdctl.sock
srwx------  1 you  staff  0 20 Aug 09:14 ~/Library/Application Support/MoreDisplays/mdctl.sock

If the app is not running there is nobody to answer, and every command exits 3. That is the first thing to check when a script that worked yesterday stops working.

Variable	Meaning
MDCTL_SOCKET	Path to the app's socket. Set by tests and support diagnostics; unset in normal use.

Options

There are almost none, on purpose. Every command takes its arguments positionally, and an unrecognised option is a usage error rather than something quietly ignored.

Option	Meaning
--help , -h	Print the usage text and exit 0. Accepted anywhere in the arguments, including before a command.
--	Ends option parsing, so a group whose name begins with a dash is still reachable.

Exit codes

Four, the same across every command, so a script can branch on the number without knowing which command produced it.

Code	Name	Meaning
0	ok	The command succeeded.
1	commandFailed	The app understood the command and refused or failed it. The reason is on stderr.
2	usage	The arguments were wrong. Nothing was sent.
3	appNotRunning	No app is listening on the socket.

There is no JSON

No command takes --json. The output is plain text designed to be read by a person and, where it is a list, by a pipe: list prints one name per line and nothing else, which is the only shape a shell needs.

$ mdctl list | wc -l
       3

status is the one command with structured output, and its structure is four labelled lines in a fixed order. Read it with cut or sed, not with a JSON parser.

$ mdctl status | sed -n '3p' | cut -d' ' -f3-
Home