Referência da API

O cmux oferece uma ferramenta CLI e um socket Unix para controle programático. Cada comando está disponível através de ambas as interfaces.

Socket

Build	Caminho
Release	`/tmp/cmux.sock`
Debug	`/tmp/cmux-debug.sock`
Build de debug com tag	`/tmp/cmux-debug-<tag>.sock`

Substitua com a variável de ambiente CMUX_SOCKET_PATH. Envie uma requisição JSON terminada em nova linha por chamada:

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

Requisições JSON via socket devem usar method e params. Payloads JSON legados v1 como {"command":"..."} não são suportados.

Modos de acesso

Modo	Descrição	Como ativar
Off	Socket desativado	Interface de Configurações ou CMUX_SOCKET_MODE=off
cmux processes only	Apenas processos iniciados dentro dos terminais do cmux podem se conectar.	Modo padrão na interface de Configurações
allowAll	Permitir qualquer processo local se conectar (sem verificação de ancestralidade).	Apenas por variável de ambiente: CMUX_SOCKET_MODE=allowAll

Em máquinas compartilhadas, use Desligado ou apenas processos cmux.

Opções da CLI

Flag	Descrição
`--socket PATH`	Caminho de socket personalizado
`--json`	Saída em formato JSON
`--window ID`	Direcionar uma janela específica
`--workspace ID`	Direcionar um workspace específico
`--surface ID`	Direcionar uma superfície específica
`--id-format refs\|uuids\|both`	Controlar formato de identificador na saída JSON

Comandos de workspace

list-workspaces

Listar todos os workspaces abertos.

CLI

cmux list-workspaces
cmux list-workspaces --json

Socket

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

new-workspace

Criar um novo workspace.

CLI

cmux new-workspace

Socket

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

select-workspace

Alternar para um workspace específico.

CLI

cmux select-workspace --workspace <id>

Socket

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

current-workspace

Obter o workspace atualmente ativo.

CLI

cmux current-workspace
cmux current-workspace --json

Socket

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

close-workspace

Fechar um workspace.

CLI

cmux close-workspace --workspace <id>

Socket

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

Comandos de divisão

new-split

Criar um novo painel dividido. Direções: 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 as superfícies no workspace atual.

CLI

cmux list-surfaces
cmux list-surfaces --json

Socket

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

focus-surface

Focar uma superfície 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 para o terminal focado.

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 uma 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 para uma superfície 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 uma tecla para uma superfície 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 notificação

notify

Enviar uma notificação.

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 as notificações.

CLI

cmux list-notifications
cmux list-notifications --json

Socket

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

clear-notifications

Limpar todas as notificações.

CLI

cmux clear-notifications

Socket

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

Comandos de metadados da barra lateral

Definir indicadores de status, barras de progresso e entradas de log na barra lateral para qualquer workspace. Útil para scripts de build, integrações de CI e agentes de código com IA que querem exibir estado rapidamente.

set-status

Definir um indicador de status na barra lateral. Use uma chave única para que diferentes ferramentas possam gerenciar suas próprias 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

Remover uma entrada de status da barra lateral por chave.

CLI

cmux clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Listar todas as entradas de status da barra lateral para um workspace.

CLI

cmux list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Definir uma barra de progresso na 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

Limpar a barra de progresso da barra lateral.

CLI

cmux clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Adicionar uma entrada de log à barra lateral. Níveis: 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

Limpar todas as entradas de log da barra lateral.

CLI

cmux clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Listar entradas de log da barra lateral.

CLI

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

Socket

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

sidebar-state

Exportar todos os metadados da barra lateral (cwd, branch git, portas, status, progresso, logs).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Comandos utilitários

ping

Verificar se o cmux está rodando e respondendo.

CLI

cmux ping

Socket

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

capabilities

Listar métodos de socket disponíveis e modo de acesso atual.

CLI

cmux capabilities
cmux capabilities --json

Socket

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

identify

Mostrar contexto da janela/workspace/painel/superfície focados.

CLI

cmux identify
cmux identify --json

Socket

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

Variáveis de ambiente

Variável	Descrição
`CMUX_SOCKET_PATH`	Substituir o caminho do socket usado pela CLI e integrações
`CMUX_SOCKET_ENABLE`	Forçar ativação/desativação do socket (1/0, true/false, on/off)
`CMUX_SOCKET_MODE`	Substituir modo de acesso (cmuxOnly, allowAll, off). Também aceita cmux-only/cmux_only e allow-all/allow_all
`CMUX_WORKSPACE_ID`	Definido automaticamente: ID do workspace atual
`CMUX_SURFACE_ID`	Definido automaticamente: ID da superfície atual
`TERM_PROGRAM`	Definido como ghostty
`TERM`	Definido como xterm-ghostty

Valores legados de CMUX_SOCKET_MODE full e notifications ainda são aceitos para compatibilidade.

Detectando o 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"

Exemplos

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 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 build com notificação

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