Muxy CLI

The muxy command talks to the server from a shell. It manages projects, terminal sessions, worktrees, server settings, and phone access. No desktop app is needed, so it works on Linux and over SSH too.

Commands work with what the server owns: projects and sessions. Tabs, panes, and workspaces belong to each app, so there are no commands for them. Browser tabs are the exception: they live in the desktop app, and muxy browser talks to the app on this computer. The terminal UI is an app of its own, with its own layout.

Install

With the desktop app: choose Install Command Line Tool… from the app menu. It links ~/.local/bin/muxy to the copy inside the app.
On its own: see Getting started.

Make sure ~/.local/bin is on your PATH.

Basics

muxy                 # open the terminal UI
muxy .               # open this folder in the desktop app or the terminal UI
muxy project list    # list projects
muxy --help          # all commands; muxy <command> --help for details

Commands start the server they use if it isn't running, including a remote one with --host. muxy server status and muxy server stop never start it.
Management commands take --json for machine-readable output, except muxy mobile.
Ending or discarding a session and deleting a project or worktree need --yes.
A project can be named by its ID, its name if unique, or its folder.
--host <destination> runs the command against the server on another computer. It must come first: muxy --host devbox project list. See Remote servers.

Commands

Command	What it does
`muxy`	Opens the terminal UI.
`muxy <folder>`	Opens the folder as a project in the desktop app. On Linux, over SSH, or without the desktop app, opens it in the terminal UI.
`muxy server start\|status\|stop`	Starts, inspects, or stops the server. `stop` refuses while terminals run; add `--force` to end them.
`muxy project list\|add\|rename\|set-color\|set-icon\|delete`	Manages projects. Deleting ends its terminals but keeps files on disk.
`muxy session list\|create\|send\|send-keys\|read-screen\|history\|search\|wait\|end\|discard`	Creates terminals, sends input, reads output, and waits for text or exit.
`muxy worktree list\|create\|checkout-pr\|register\|remove`	Manages Git worktree projects, including checking out pull requests.
`muxy settings get\|set`	Reads or changes server settings.
`muxy activity list\|ack`	Reads or clears AI agent activity.
`muxy browser open\|list\|read\|click\|…`	Drives browser tabs in the desktop app on this computer. See Browser control.
`muxy exec <project> -- <program> [args]`	Runs a program in the project folder, without a shell.
`muxy git`, `muxy files`	Run raw server Git and file actions as JSON. Advanced; the JSON shape follows the protocol and may change.
`muxy mobile`	Turns on phone access and pairs phones. See Mobile.
`muxy install-skills`	Installs the Muxy CLI skill for the AI agents found in your home folder. `--dir <path>` adds another skills folder.
`muxy stdio`	Joins stdin and stdout to the server. Used by `--host` over SSH; you don't run it yourself.

Sessions from a script

id=$(muxy session create my-app)
muxy session send "$id" "npm test"
muxy session send-keys "$id" Enter
muxy session read-screen "$id" --lines 20
muxy session end "$id" --yes

send types text without pressing Return. send-keys sends Enter, Tab, Escape, Backspace, Ctrl+C, Ctrl+D, or Ctrl+Z.
read-screen returns the last visible rows. history and search page through scrollback as JSON.
--saved reads a session's last saved screen, even after it ended.
end stops the program and keeps its saved output. discard also deletes the output.
Sessions created here outlive the command and appear in every app under Existing Terminals.
Inside a Muxy terminal, session commands default to that terminal, and create to its project.
create can take a --directory and a command to run after --.
wait --text <text> waits for text on the screen, and wait --exit for the shell to exit. Both give up after 30 seconds by default.

Browser control

tab=$(muxy browser open localhost:3000)
muxy browser wait-for-navigation "$tab"
muxy browser fill "$tab" "#email" "[email protected]"
muxy browser click "$tab" "button[type=submit]"
muxy browser wait "$tab" --text "Welcome"
muxy browser read "$tab"
muxy browser screenshot "$tab" | base64 -D > page.png
muxy browser close "$tab"

Browser commands need the desktop app and don't take --host. open starts the app if it isn't running.
open prints the new tab's ID. Pass it to the other commands.
snapshot lists a page's interactive elements, each with a selector for click, fill, or type.
muxy browser --help lists every command.

Exit codes

0 on success. On any error, muxy prints muxy: <message> to stderr and exits with 1, including when a program run with muxy exec fails.

Profiles

MUXY_DIR points the CLI, and the server it starts, at another profile folder. Use it to run a separate, throwaway server. See Server.