Referencia de API

cmux proporciona tanto una herramienta CLI como un socket Unix para control programático. Cada comando está disponible a través de ambas interfaces.

Socket

Build	Ruta
Release	`/tmp/cmux.sock`
Debug	`/tmp/cmux-debug.sock`
Build de debug etiquetado	`/tmp/cmux-debug-<tag>.sock`

Sobrescriba con la variable de entorno CMUX_SOCKET_PATH. Envíe una solicitud JSON terminada en salto de línea por llamada:

{"id":"req-1","method":"workspace.list","params":{}}
// Response:
{"id":"req-1","ok":true,"result":{"workspaces":[...]}}

Las solicitudes JSON del socket deben usar method y params. Los payloads JSON legacy v1 como {"command":"..."} no son compatibles.

Modos de acceso

Modo	Descripción	Cómo habilitar
Off	Socket desactivado	UI de configuración o CMUX_SOCKET_MODE=off
cmux processes only	Solo los procesos iniciados dentro de terminales de cmux pueden conectarse.	Modo predeterminado en la UI de configuración
allowAll	Permitir que cualquier proceso local se conecte (sin verificación de origen).	Solo por variable de entorno: CMUX_SOCKET_MODE=allowAll

En máquinas compartidas, use Desactivado o Solo procesos de cmux.

Opciones de CLI

Flag	Descripción
`--socket PATH`	Ruta de socket personalizada
`--json`	Salida en formato JSON
`--window ID`	Dirigirse a una ventana específica
`--workspace ID`	Dirigirse a un workspace específico
`--surface ID`	Dirigirse a una superficie específica
`--id-format refs\|uuids\|both`	Controlar el formato de identificador en la salida JSON

Comandos de workspace

list-workspaces

Listar todos los workspaces abiertos.

CLI

cmux list-workspaces
cmux list-workspaces --json

Socket

{"id":"ws-list","method":"workspace.list","params":{}}

new-workspace

Crear un nuevo workspace.

CLI

cmux new-workspace

Socket

{"id":"ws-new","method":"workspace.create","params":{}}

select-workspace

Cambiar a un workspace específico.

CLI

cmux select-workspace --workspace <id>

Socket

{"id":"ws-select","method":"workspace.select","params":{"workspace_id":"<id>"}}

current-workspace

Obtener el workspace actualmente activo.

CLI

cmux current-workspace
cmux current-workspace --json

Socket

{"id":"ws-current","method":"workspace.current","params":{}}

close-workspace

Cerrar un workspace.

CLI

cmux close-workspace --workspace <id>

Socket

{"id":"ws-close","method":"workspace.close","params":{"workspace_id":"<id>"}}

Comandos de división

new-split

Crear un nuevo panel dividido. Direcciones: left, right, up, down.

CLI

cmux new-split right
cmux new-split down

Socket

{"id":"split-new","method":"surface.split","params":{"direction":"right"}}

list-surfaces

Listar todas las superficies en el workspace actual.

CLI

cmux list-surfaces
cmux list-surfaces --json

Socket

{"id":"surface-list","method":"surface.list","params":{}}

focus-surface

Enfocar una superficie específica.

CLI

cmux focus-surface --surface <id>

Socket

{"id":"surface-focus","method":"surface.focus","params":{"surface_id":"<id>"}}

Comandos de entrada

send

Enviar texto al terminal enfocado.

CLI

cmux send "echo hello"
cmux send "ls -la\n"

Socket

{"id":"send-text","method":"surface.send_text","params":{"text":"echo hello\n"}}

send-key

Enviar una pulsación de tecla. Teclas: enter, tab, escape, backspace, delete, up, down, left, right.

CLI

cmux send-key enter

Socket

{"id":"send-key","method":"surface.send_key","params":{"key":"enter"}}

send-surface

Enviar texto a una superficie específica.

CLI

cmux send-surface --surface <id> "command"

Socket

{"id":"send-surface","method":"surface.send_text","params":{"surface_id":"<id>","text":"command"}}

send-key-surface

Enviar una pulsación de tecla a una superficie específica.

CLI

cmux send-key-surface --surface <id> enter

Socket

{"id":"send-key-surface","method":"surface.send_key","params":{"surface_id":"<id>","key":"enter"}}

Comandos de notificación

notify

Enviar una notificación.

CLI

cmux notify --title "Title" --body "Body"
cmux notify --title "T" --subtitle "S" --body "B"

Socket

{"id":"notify","method":"notification.create","params":{"title":"Title","subtitle":"S","body":"Body"}}

list-notifications

Listar todas las notificaciones.

CLI

cmux list-notifications
cmux list-notifications --json

Socket

{"id":"notif-list","method":"notification.list","params":{}}

clear-notifications

Borrar todas las notificaciones.

CLI

cmux clear-notifications

Socket

{"id":"notif-clear","method":"notification.clear","params":{}}

Comandos de metadatos de la barra lateral

Establezca indicadores de estado, barras de progreso y entradas de registro en la barra lateral para cualquier workspace. Útil para scripts de compilación, integraciones de CI y agentes de programación con IA que quieran mostrar el estado de un vistazo.

set-status

Establecer un indicador de estado en la barra lateral. Use una clave única para que diferentes herramientas puedan gestionar sus propias entradas.

CLI

cmux set-status build "compiling" --icon hammer --color "#ff9500"
cmux set-status deploy "v1.2.3" --workspace workspace:2

Socket

set_status build compiling --icon=hammer --color=#ff9500 --tab=<workspace-uuid>

clear-status

Eliminar una entrada de estado de la barra lateral por clave.

CLI

cmux clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Listar todas las entradas de estado de la barra lateral para un workspace.

CLI

cmux list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Establecer una barra de progreso en la barra lateral (0.0 a 1.0).

CLI

cmux set-progress 0.5 --label "Building..."
cmux set-progress 1.0 --label "Done"

Socket

set_progress 0.5 --label=Building... --tab=<workspace-uuid>

clear-progress

Borrar la barra de progreso de la barra lateral.

CLI

cmux clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Añadir una entrada de registro a la barra lateral. Niveles: info, progress, success, warning, error.

CLI

cmux log "Build started"
cmux log --level error --source build "Compilation failed"
cmux log --level success -- "All 42 tests passed"

Socket

log --level=error --source=build --tab=<workspace-uuid> -- Compilation failed

clear-log

Borrar todas las entradas de registro de la barra lateral.

CLI

cmux clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Listar las entradas de registro de la barra lateral.

CLI

cmux list-log
cmux list-log --limit 5

Socket

list_log --limit=5 --tab=<workspace-uuid>

sidebar-state

Volcar todos los metadatos de la barra lateral (cwd, rama de git, puertos, estado, progreso, registros).

CLI

cmux sidebar-state
cmux sidebar-state --workspace workspace:2

Socket

sidebar_state --tab=<workspace-uuid>

Comandos de utilidad

ping

Verificar si cmux está ejecutándose y responde.

CLI

cmux ping

Socket

{"id":"ping","method":"system.ping","params":{}}
// Response: {"id":"ping","ok":true,"result":{"pong":true}}

capabilities

Listar los métodos de socket disponibles y el modo de acceso actual.

CLI

cmux capabilities
cmux capabilities --json

Socket

{"id":"caps","method":"system.capabilities","params":{}}

identify

Mostrar el contexto de ventana/workspace/panel/superficie enfocados.

CLI

cmux identify
cmux identify --json

Socket

{"id":"identify","method":"system.identify","params":{}}

Variables de entorno

Variable	Descripción
`CMUX_SOCKET_PATH`	Sobrescribir la ruta del socket utilizada por la CLI e integraciones
`CMUX_SOCKET_ENABLE`	Forzar la activación/desactivación del socket (1/0, true/false, on/off)
`CMUX_SOCKET_MODE`	Sobrescribir el modo de acceso (cmuxOnly, allowAll, off). También acepta cmux-only/cmux_only y allow-all/allow_all
`CMUX_WORKSPACE_ID`	Establecido automáticamente: ID del workspace actual
`CMUX_SURFACE_ID`	Establecido automáticamente: ID de la superficie actual
`TERM_PROGRAM`	Establecido en ghostty
`TERM`	Establecido en xterm-ghostty

Los valores legacy de CMUX_SOCKET_MODE full y notifications siguen siendo aceptados por compatibilidad.

Detectar cmux

bash

# Prefer explicit socket path if set
SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"
[ -S "$SOCK" ] && echo "Socket available"

# Check for the CLI
command -v cmux &>/dev/null && echo "cmux available"

# In cmux-managed terminals these are auto-set
[ -n "${CMUX_WORKSPACE_ID:-}" ] && [ -n "${CMUX_SURFACE_ID:-}" ] && echo "Inside cmux surface"

# Distinguish from regular Ghostty
[ "$TERM_PROGRAM" = "ghostty" ] && [ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "In cmux"

Ejemplos

Cliente Python

python

import json
import os
import socket

SOCKET_PATH = os.environ.get("CMUX_SOCKET_PATH", "/tmp/cmux.sock")

def rpc(method, params=None, req_id=1):
    payload = {"id": req_id, "method": method, "params": params or {}}
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(SOCKET_PATH)
        sock.sendall(json.dumps(payload).encode("utf-8") + b"\n")
        return json.loads(sock.recv(65536).decode("utf-8"))

# List workspaces
print(rpc("workspace.list", req_id="ws"))

# Send notification
print(rpc(
    "notification.create",
    {"title": "Hello", "body": "From Python!"},
    req_id="notify"
))

Script de shell

bash

#!/bin/bash
SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"

cmux_cmd() {
    printf "%s\n" "$1" | nc -U "$SOCK"
}

cmux_cmd '{"id":"ws","method":"workspace.list","params":{}}'
cmux_cmd '{"id":"notify","method":"notification.create","params":{"title":"Done","body":"Task complete"}}'

Script de compilación con notificación

bash

#!/bin/bash
npm run build
if [ $? -eq 0 ]; then
    cmux notify --title "✓ Build Success" --body "Ready to deploy"
else
    cmux notify --title "✗ Build Failed" --body "Check the logs"
fi