/muxy-cli

name: muxy-cli
description: How to drive Muxy 2 from a shell with the `muxy` command — start terminals that keep running, type into them, read and wait on their output, and manage projects and Git worktrees. Use this when you are an agent running inside a Muxy terminal (or any script on the same computer) and want work to run in its own terminal instead of blocking yours, or to drive the desktop app's built-in browser.

Muxy CLI

Muxy keeps terminals in a background server. The `muxy` command talks to that server directly; the desktop app doesn't need to be open. Terminals you start keep running after your command returns, and the user can open them in the desktop app or the terminal UI from **Existing Terminals**, or you can show one to them with `muxy session show`.

Run `muxy --help` for command groups and `muxy help session create` (or `muxy session create --help`) for one command. Add `--json` to management commands for machine-readable output. Pipes keep their original text formats; terminals get formatted tables. Project/session/worktree lists accept `--quiet` (`-q`) for IDs only; do not combine it with `--json`.

Short aliases: `ls` = `session list`, `new` = `session create`, `send` = `session send`, `send-key` = `session send-keys`, `capture` = `session read-screen`, and `wait` = `session wait`.

When to use it

• Start a long-running process (a dev server, a test watcher, a log tail) in its

own terminal, then check on it later.

• Wait until that process prints something, or exits, before going on.
• Create a Git worktree for a task, with the user's configured location.

Don't use it for work a plain command can do in your own terminal.

Inside a Muxy terminal

Muxy sets `MUXY_SESSION_ID` and `MUXY_SERVER_ID` in every terminal. Session commands then default to your own terminal, and `session create` to your project, so most commands need no IDs.

Start a terminal and capture its ID

`session create` prints the new session ID. Everything after `--` is typed into the new terminal, followed by Return. Capture the ID; never guess one.

WEB=$(muxy session create -- npm run dev)
TESTS=$(muxy session create MyProject --directory ./packages/api -- exec npm test)

Outside a Muxy terminal, name the project: an ID, a unique name, or its folder.

The words after `--` are joined with spaces, so quote the whole command to keep its own quotes, pipes, or `;`:

muxy session create -- 'grep -rn "TODO list" src | wc -l'

Wait instead of polling

muxy session wait "$WEB" --text "ready" --timeout-ms 120000   # prints the matching line
muxy session wait "$TESTS" --exit                              # prints how it ended

`wait` fails with a nonzero exit if the timeout passes (default 30 s) or, for `--text`, if the terminal ends without showing the text. It looks at the visible screen, not scrollback. Don't wait on your own terminal: it is busy running `muxy`.

`--exit` waits for the terminal's shell to end. Use `exec` for a one-shot command, as in the test example, so the program replaces the shell and its exit ends the session. Without `exec`, the shell stays open after the program finishes.

Read output

muxy session read-screen "$WEB" --lines 40     # last visible rows, not scrollback
muxy session search "$WEB" "error" --ignore-case
muxy session history "$WEB" --limit 200        # JSON, paged with --before

After a terminal ends, add `--saved` to read its last saved output.

Send input deliberately

`send` types text without pressing Return; `send-keys` presses one or more keys in order (Enter, Tab, Escape, Backspace, Ctrl+C, Ctrl+D, Ctrl+Z). `send --stdin` sends piped or redirected bytes verbatim, including newlines, up to 1 MiB. Larger input sends nothing; no text argument is allowed with it.

muxy session send-keys "$WEB" Ctrl+C
muxy session read-screen "$WEB"
muxy session send "$WEB" "npm run dev"
muxy session send-keys "$WEB" Enter

You are typing into a live terminal. Read the screen first if you are unsure what is running.

Inspect and name terminals

muxy project inspect MyProject --json
muxy session inspect "$WEB" --json
muxy session rename "$WEB" dev-server
muxy session list --project MyProject --quiet

Inspection works for live and saved sessions. Renaming updates the shared name shown in every app; IDs stay unchanged and remain the targets for commands.

End terminals you started

muxy session list --project MyProject     # id, project-id, status, attached, directory
muxy session end "$WEB" --yes

Only end terminals you created. A terminal the user is looking at closes in their app too.

Show a terminal to the user

muxy session show "$WEB"

This opens the terminal in a new tab of its project in the desktop app, or selects the tab that already shows it, without raising the app. Use it when the user should watch or take over a terminal, not for every terminal you start.

Projects and worktrees

muxy project list
muxy project add ~/code/app --reuse                 # prints the existing project if there is one
muxy worktree create MyProject login                # branch "login" from HEAD, default location
muxy worktree create MyProject fix --branch fix/x --base main --hooks
muxy worktree list MyProject
muxy worktree remove login --yes

`--hooks` runs the setup or teardown commands from `.muxy/worktree.json`; ask the user before using it. `worktree remove` refuses uncommitted changes unless `--force` is given; never pass `--force` without the user's consent.

Browser

`muxy browser` drives tabs in the desktop app's built-in browser: open a page, read it, click and type, take screenshots. It talks to the desktop app on this Mac, so it needs the app (`open` starts it) and never takes `--host`.

TAB=$(muxy browser open http://localhost:3000)    # prints the new tab's ID
muxy browser wait-for-navigation "$TAB"
muxy browser snapshot "$TA