The macterm CLI

The macterm command controls the running app: projects, tabs, panes and their zmx sessions. It uses a local Unix socket.

Each shell that Macterm starts already has macterm in its PATH:

$ macterm status
Macterm 1.4.0 (pid 4242) — active project: api

$ macterm tab new --run "npm run dev"
tab:3  *  npm  1 pane

$ macterm grid 2x2 --run "tail -f log/dev.log"

In any other shell, use the bundle path, or make a symlink to it in a folder in your PATH:

/Applications/Macterm.app/Contents/Resources/bin/macterm status

Every command that talks to the app accepts --json for a payload that a script can read. It also accepts --socket <path> to select one instance of the app. --help works at every level.

Commands

The grammar is macterm <noun> <verb> [options]. A noun with no verb means list.

Starting a background terminal

tab new --no-focus starts the shell of a tab and does not change the selected tab. An empty workspace takes its first tab with no focus history. pane split --no-focus starts a split and does not move the pane focus or clear the zoom. Neither command switches projects or windows. This is also true when the target project or tab is not visible. In a project that you unloaded, only the tab that started becomes undimmed. A background split also starts the existing panes of that tab, so the source of the split is usable. Other tabs stay stopped and dimmed until you select the project. Without the flag, creation selects the new tab or pane as usual.

macterm tab new --project api --no-focus --run "npm test"
macterm pane split --session "$MACTERM_SESSION" --no-focus --run "npm run dev"

The shell starts with no visit to the child, with or without --run. Creation returns before the shell is ready for more input. If you use pane run, wait for the shell prompt. Use --json to get the identity of the new tab or pane. Use pane list --project P --tab T to find the session of a new tab. tab new uses the active project by default. It does not use the project of the caller. If the two can be different, pass --project.

In an automation, select the app with --socket. When the running app is too old for --no-focus, the CLI refuses the command before it creates anything. The CLI asks the app for its protocol version first. It exits with an error and does not switch the view of the user in silence. Use the CLI that is in the app that you target. The --help of a newer CLI shows only that the flag exists in that CLI. It does not show that an older running app has it.

Targeting a pane

Projects and tabs accept a name, a UUID or the index from the list output, counted from 1 (3 or tab:3). A name that two items have gives an ambiguous error. The CLI never selects the first match in silence.

Pane commands find their target in this order:

1. --session <name>: the zmx session name. It is stable across restarts. Pane UUIDs change at every start, and session names do not. The CLI finds the session in the project that holds it, unless --project names a project.
2. --pane <uuid|index>.
3. MACTERM_SESSION: inside a pane. A bare macterm pane split therefore splits the pane that you are in. An explicit --tab turns this off.
4. In all other cases, the focused pane of the active tab.

The pane of a desktop widget belongs to no project. pane dump, pane inspect, pane run and pane key reach it with --session only. Inside the widget, they also reach it with MACTERM_SESSION.

pane close never uses MACTERM_SESSION. pane focus --direction treats the resolved target as the origin. It reports the pane that has the focus at the end.

Typing into a pane

pane run types everything after -- exactly as you wrote it, with the dashes:

macterm pane run --session macterm-api-8f327ce4a3f8 -- ls -la

Before --, its own flags are read at any place (--no-submit, the target selectors, --socket and --json). Words with no leading dash are typed. So macterm pane run ls and macterm pane run clear --session macterm-api-8f327ce4a3f8 need no --. Any other word that starts with - before -- is an error, and nothing is typed. For example, macterm pane run ls -la fails. It prints the same command with its text after --. --help before -- prints help.

Reading a pane

$ macterm pane inspect
session             macterm-api-8f327ce4a3f8
grid                132×65
cell px             16×40
surface px          2176×2682
scrollback          360 total, 295 offset, 65 len
alt-screen          false
content scale       2.0
foreground          79497 (nvim src/main.rs)
process exited      false
needs confirm quit  false

pane dump prints the text of the viewport. --scrollback adds the full scrollback before it. It reads the own cells of the terminal, so it sees what a full-screen program draws.

Both commands need a live surface. A pane that you never showed returns no_surface. Select its tab one time.

The C ABI of libghostty does not give the cursor position, and it has no direct alt-screen query. alt-screen here is a guess. It shows - until the surface sends its first scrollbar update.

Skills for coding agents

macterm skills prints Agent Skills. These are SKILL.md files that Claude Code, Codex, OpenCode, Gemini CLI, Cursor and other agents load from a skills directory. They teach an agent this CLI:

• macterm-panes: run commands in panes and read their output.
• macterm-workspace: build a workspace that persists.
• macterm-subagents: run sub-agents in panes of their own.

There is no installer. The agent installs the skills. Give it this prompt:

Run `macterm skills` and install each skill it prints into your skills directory as <name>/SKILL.md, exactly as printed. Then tell me what you installed and where.

macterm skills <name> prints one skill as it is. For example, macterm skills macterm-panes > <skills dir>/macterm-panes/SKILL.md installs it. --list shows the names. The text is inside the CLI, so it always matches your version. Install the skills again after you update Macterm.

Environment

Macterm exports these variables into every shell that it starts:

Exit codes

stdout has output only when a command succeeds. All other text goes to stderr.

To make a script wait until the app is ready, use this loop:

until macterm status >/dev/null 2>&1; do sleep 0.2; done

Scripting example

#!/bin/sh
set -e
mac=/Applications/Macterm.app/Contents/Resources/bin/macterm

# Wait for the app, then open the repo as a project.
until "$mac" status >/dev/null 2>&1; do sleep 0.2; done
"$mac" project create ~/dev/myapp --select

# A tab running the dev server, split for a test watcher.
"$mac" tab new --run "npm run dev"
"$mac" pane split --direction down --run "npm test -- --watch"

Wire protocol

Any process of the same user can use the protocol directly. Use one request for each connection to ~/Library/Application Support/Macterm/control.sock. Write one JSON line that ends with a newline. Close the write end of your connection. Read one line back.

{"v":1,"id":"<any-string>","command":"pane.split","args":{"direction":"down","run":"btop"}}

v is the minimum protocol version that the request needs. It is not the version of the client. Ordinary commands use 1. --no-focus sends "v":2 with "focus":false. From v2, servers reject a request version that they do not support. Before dispatch, they check it. The v1 apps that shipped earlier ignore v. A direct client must therefore probe status first. It checks the response version before it sends newer fields. The CLI does this by itself and pins the command to the verified socket.

{"v":2,"id":"<echoed>","ok":true,"data":{"panes":[{"id":"…","session":"macterm-api-1a2b3c4d5e6f","index":2}]}}

A failure looks like {"ok":false,"error":{"code":"…","message":"…","action":"…"}}. The codes are starting, unknown_command, bad_request, not_found, ambiguous, busy, no_surface, unsupported_version and internal. Both sides ignore unknown fields. When a field must not be ignored in silence, use the version checks above.

echo '{"v":1,"id":"x","command":"status"}' | nc -U ~/Library/Application\ Support/Macterm/control.sock

The socket has mode 0600 in a directory with mode 0700. The CLI refuses sockets that another user owns. Only the same user can use it. There is no token authentication.