# Referência da CLI 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-.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 ``` Socket ``` {"id":"ws-select","method":"workspace.select","params":{"workspace_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 ``` Socket ``` {"id":"ws-close","method":"workspace.close","params":{"workspace_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 cmux new-split down --command "npm run dev" ``` Socket ``` {"id":"split-new","method":"surface.split","params":{"direction":"right"}} {"id":"split-cmd","method":"surface.split","params":{"direction":"down","initial_input":"npm run dev\r"}} ``` #### list-panels Listar todas as superfícies no workspace atual. CLI ``` cmux list-panels cmux list-panels --json ``` Socket ``` {"id":"surface-list","method":"surface.list","params":{}} ``` #### list-pane-surfaces Listar as superfícies no painel em foco. CLI ``` cmux list-pane-surfaces cmux list-pane-surfaces --json ``` Socket ``` {"id":"pane-surfaces","method":"pane.surfaces","params":{}} ``` #### focus-panel Focar uma superfície específica. CLI ``` cmux focus-panel --panel ``` Socket ``` {"id":"surface-focus","method":"surface.focus","params":{"surface_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 "command" ``` Socket ``` {"id":"send-surface","method":"surface.send_text","params":{"surface_id":"","text":"command"}} ``` #### send-key --surface Enviar uma tecla para uma superfície específica. CLI ``` cmux send-key --surface enter ``` Socket ``` {"id":"send-key-surface","method":"surface.send_key","params":{"surface_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" --priority 80 cmux set-status deploy "v1.2.3" --workspace workspace:2 ``` Socket ``` set_status build compiling --icon=hammer --color=#ff9500 --priority=80 --tab= ``` #### clear-status Remover uma entrada de status da barra lateral por chave. CLI ``` cmux clear-status build ``` Socket ``` clear_status build --tab= ``` #### list-status Listar todas as entradas de status da barra lateral para um workspace. CLI ``` cmux list-status ``` Socket ``` list_status --tab= ``` #### 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= ``` #### clear-progress Limpar a barra de progresso da barra lateral. CLI ``` cmux clear-progress ``` Socket ``` clear_progress --tab= ``` #### 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= -- Compilation failed ``` #### clear-log Limpar todas as entradas de log da barra lateral. CLI ``` cmux clear-log ``` Socket ``` clear_log --tab= ``` #### list-log Listar entradas de log da barra lateral. CLI ``` cmux list-log cmux list-log --limit 5 ``` Socket ``` list_log --limit=5 --tab= ``` #### 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= ``` ## 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 ``` Canonical: https://cmux.com/pt-BR/docs/api Documentation index: https://cmux.com/llms.txt