The cmux CLI provides a convenient interface to control cmux via the Unix socket.
Installation The cmux CLI is bundled with cmux.app and automatically added to /usr/local/bin/cmux when you first launch the app.
Verify installation:
Global flags These flags can be used with any command:
--socket
string
default: "/tmp/cmux.sock"
Path to the Unix socket. Defaults to CMUX_SOCKET_PATH env var or /tmp/cmux.sock.
Output JSON instead of human-readable text.
Output format for handles: refs, uuids, or both.
Target a specific window by ID, ref, or index. Commands will focus this window first.
Socket password for authentication (overrides CMUX_SOCKET_PASSWORD env var).
Open directory Open a directory in cmux (launches cmux if not running):
Current directory
Specific path
Home directory
System commands version Show cmux version:
ping Test socket connectivity:
capabilities List socket API capabilities:
identify Get information about the current context:
cmux identify cmux identify --workspace workspace:1 cmux identify --surface surface:2 cmux identify --no-caller # omit caller context
Window commands list-windows List all windows:
cmux list-windows cmux list-windows --json
current-window Get the current window ID:
new-window Create a new window:
focus-window Focus a window:
cmux focus-window --window window:1 cmux focus-window --window 0 # by index
close-window Close a window:
cmux close-window --window window:1
Workspace commands list-workspaces List all workspaces:
cmux list-workspaces cmux list-workspaces --json
Output: workspace:1 Project A * workspace:2 Project B [selected] workspace:3
new-workspace Create a new workspace:
cmux new-workspace cmux new-workspace --cwd ~/projects/my-app cmux new-workspace --cwd ~/dev --command "npm run dev"
Set the working directory for the new workspace.
Run a command after creating the workspace (automatically appends \\n).
current-workspace Get the current workspace ID:
select-workspace Switch to a workspace:
cmux select-workspace --workspace workspace:2 cmux select-workspace --workspace 1 # by index
close-workspace Close a workspace:
cmux close-workspace --workspace workspace:1
rename-workspace Rename a workspace:
cmux rename-workspace My Project cmux rename-workspace --workspace workspace:2 Backend Server
move-workspace-to-window Move a workspace to a different window:
cmux move-workspace-to-window --workspace workspace:1 --window window:2
reorder-workspace Reorder workspaces in the sidebar:
cmux reorder-workspace --workspace workspace:3 --index 0 cmux reorder-workspace --workspace workspace:1 --before workspace:2 cmux reorder-workspace --workspace workspace:1 --after workspace:3
workspace-action Perform workspace actions:
cmux workspace-action --action next cmux workspace-action --action previous cmux workspace-action --action last cmux workspace-action --action rename --title "New Name" cmux workspace-action --workspace workspace:1 --action select
Available actions:
next, previous, last: Navigate workspacesselect: Switch to workspaceclose: Close workspacerename: Rename workspace (requires --title)
Pane commands list-panes List panes in a workspace:
cmux list-panes cmux list-panes --workspace workspace:1
new-pane Create a new pane:
cmux new-pane --direction right cmux new-pane --type browser --direction down --url https://example.com cmux new-pane --workspace workspace:1 --direction left
Pane type: terminal or browser.
Split direction: left, right, up, down.
Target workspace ID/ref/index.
focus-pane Focus a pane:
cmux focus-pane --pane pane:1 cmux focus-pane --pane 0 --workspace workspace:1
list-pane-surfaces List surfaces in a pane:
cmux list-pane-surfaces --pane pane:1 cmux list-pane-surfaces --pane 0 --workspace workspace:1
Surface/tab commands list-panels List surfaces (also called “panels” or “tabs”) in a workspace:
cmux list-panels cmux list-panels --workspace workspace:1
new-surface Create a new surface in a pane:
cmux new-surface cmux new-surface --type browser --url https://example.com cmux new-surface --pane pane:1 --workspace workspace:1
new-split Create a split from the current surface:
cmux new-split right cmux new-split down --workspace workspace:1 cmux new-split left --surface surface:2
close-surface Close a surface:
cmux close-surface cmux close-surface --surface surface:3 --workspace workspace:1
focus-panel Focus a surface:
cmux focus-panel --panel surface:2 cmux focus-panel --panel 1 --workspace workspace:1
move-surface Move a surface to a different pane/workspace/window:
cmux move-surface --surface surface:1 --pane pane:2 cmux move-surface --surface 0 --workspace workspace:2 cmux move-surface --surface surface:1 --before surface:3 cmux move-surface --surface surface:1 --index 0 --focus true
reorder-surface Reorder surfaces within a pane:
cmux reorder-surface --surface surface:3 --index 0 cmux reorder-surface --surface surface:1 --before surface:2
tab-action Perform tab actions (surfaces can be called “tabs”):
cmux tab-action --action next cmux tab-action --action previous cmux tab-action --action close --tab tab:2 cmux tab-action --action rename --title "Build Output"
Available actions:
next, previous: Navigate tabsclose: Close tabrename: Rename tab (requires --title)reload: Reload browser tab (requires --url for terminal tabs)
rename-tab Rename a tab:
cmux rename-tab My Terminal cmux rename-tab --tab tab:2 Backend Logs cmux rename-tab --workspace workspace:1 --surface surface:3 Tests
Terminal I/O commands read-screen Read terminal screen content:
cmux read-screen cmux read-screen --scrollback cmux read-screen --lines 100 cmux read-screen --workspace workspace:1 --surface surface:2
Include scrollback buffer.
Number of lines to read (implies --scrollback).
send Send text to a terminal:
cmux send git status cmux send --workspace workspace:1 npm run dev cmux send --surface surface:2 "echo hello \\ necho world"
Use \\n for newlines and \\t for tabs. The CLI automatically unescapes these sequences.
send-key Send a key sequence to a terminal:
cmux send-key ctrl+c cmux send-key enter cmux send-key --surface surface:1 escape
Notification commands notify Create a notification:
cmux notify --title "Build Complete" --subtitle "Success" --body "App deployed" cmux notify --title "Error" --body "Tests failed" --workspace workspace:1
list-notifications List all notifications:
cmux list-notifications cmux list-notifications --json
clear-notifications Clear all notifications:
These commands update workspace sidebar UI with status, progress, and logs:
set-status Set a status indicator:
cmux set-status build Running cmux set-status deploy Success --icon checkmark --color "#00ff00" cmux set-status error "Connection failed" --icon warning --color "#ff0000"
clear-status Clear a status indicator:
list-status List all status indicators:
cmux list-status cmux list-status --workspace workspace:1
set-progress Set a progress indicator:
cmux set-progress 0.5 cmux set-progress 0.75 --label "Deploying..." cmux set-progress 1.0 --workspace workspace:2
clear-progress Clear progress indicator:
log Add a log entry to the workspace sidebar:
cmux log "Server started on port 3000" cmux log "Warning: deprecated API" --level warn --source server cmux log "Fatal error" --level error --workspace workspace:1
Log level: info, warn, error, debug.
list-log List log entries:
cmux list-log cmux list-log --limit 50 --workspace workspace:1
clear-log Clear all log entries:
cmux clear-log cmux clear-log --workspace workspace:1
Browser automation commands All browser commands use the browser subcommand:
cmux browser [--surface < i d > ] < subcomman d > [options]
browser open Open a URL in a new browser split:
cmux browser open https://example.com cmux browser open-split https://github.com
browser navigate Navigate to a URL:
cmux browser navigate https://google.com cmux browser goto https://news.ycombinator.com --snapshot-after
browser back/forward/reload Browser navigation:
cmux browser back cmux browser forward cmux browser reload --snapshot-after
browser url Get current URL:
cmux browser url cmux browser get-url --surface surface:1
browser snapshot Capture page snapshot (accessibility tree):
cmux browser snapshot cmux browser snapshot --interactive cmux browser snapshot --selector ".main-content" --max-depth 3 cmux browser snapshot --compact --cursor
Include only interactive elements.
Show which element has focus.
CSS selector to scope snapshot.
browser eval Execute JavaScript:
cmux browser eval "document.title" cmux browser eval "return window.innerWidth"
browser wait Wait for page conditions:
cmux browser wait --selector ".loading" --timeout 5 cmux browser wait --text "Success" cmux browser wait --url-contains "complete" cmux browser wait --load-state interactive cmux browser wait --function "() => document.readyState === 'complete'"
browser click/hover/focus Interact with elements:
cmux browser click "button.submit" cmux browser dblclick "#item" cmux browser hover ".menu-item" cmux browser focus "input[name='username']" cmux browser scroll-into-view ".footer"
browser type/fill Fill input fields:
cmux browser type "input[name='email']" [email protected] cmux browser fill "textarea" "Long text content" cmux browser fill "input" "" # clear input
browser press Press keyboard keys:
cmux browser press Enter cmux browser press Escape cmux browser keydown Control cmux browser keyup Control
browser get Extract element data:
cmux browser get text ".title" cmux browser get html "#content" cmux browser get value "input[name='email']" cmux browser get attr "img" --attr src cmux browser get count ".item" cmux browser get box ".element" cmux browser get styles ".button" --property color cmux browser get title cmux browser get url
browser is Check element state:
cmux browser is visible ".modal" cmux browser is enabled "button.submit" cmux browser is checked "input[type='checkbox']"
browser find Find elements by locator:
cmux browser find role button --name Submit cmux browser find text "Click here" --exact cmux browser find label "Email" cmux browser find placeholder "Enter your name" cmux browser find testid login-button cmux browser find first ".item" cmux browser find last ".item" cmux browser find nth ".item" 2
browser screenshot Capture screenshot:
cmux browser screenshot --out page.png cmux browser screenshot --json # base64 output
Tmux compatibility commands These commands provide tmux-like functionality:
capture-pane Alias for read-screen:
cmux capture-pane --scrollback cmux capture-pane --lines 100 --surface surface:1
resize-pane Resize a pane:
cmux resize-pane --pane pane:1 -R 10 cmux resize-pane --pane pane:2 -L 5 cmux resize-pane --pane pane:1 -U --amount 3
last-pane Switch to last focused pane:
cmux last-pane cmux last-pane --workspace workspace:1
next-window / previous-window Navigate workspaces:
cmux next-window cmux previous-window cmux last-window
clear-history Clear terminal scrollback:
cmux clear-history cmux clear-history --surface surface:1
Advanced commands tree Show workspace hierarchy:
cmux tree cmux tree --all # all workspaces cmux tree --workspace workspace:1
surface-health Check surface status:
cmux surface-health cmux surface-health --workspace workspace:1 --json
trigger-flash Flash a surface visually:
cmux trigger-flash cmux trigger-flash --surface surface:2
drag-surface-to-split Drag surface to create split:
cmux drag-surface-to-split --surface surface:1 right cmux drag-surface-to-split --surface 0 down
refresh-surfaces Refresh all surfaces:
Exit codes
0: Success1: Error (error message written to stderr)
Examples Create workspace and run dev server
Monitor logs from current terminal
Automate browser testing
Send command to all workspaces
cmux new-workspace --cwd ~/projects/app --command "npm run dev"