# Riferimento CLI cmux fornisce sia uno strumento CLI che un socket Unix per il controllo programmatico. Ogni comando è disponibile tramite entrambe le interfacce. ## Socket | Build | Percorso | | --- | --- | | Release | `/tmp/cmux.sock` | | Debug | `/tmp/cmux-debug.sock` | | Build debug con tag | `/tmp/cmux-debug-.sock` | Sovrascrivi con la variabile d'ambiente CMUX\_SOCKET\_PATH. Invia una richiesta JSON terminata da newline per chiamata: ``` {"id":"req-1","method":"workspace.list","params":{}} // Response: {"id":"req-1","ok":true,"result":{"workspaces":[...]}} ``` Le richieste JSON del socket devono usare method e params. I vecchi payload JSON v1 come `{"command":"..."}` non sono supportati. ## Modalità di accesso | Modalità | Descrizione | Come attivare | | --- | --- | --- | | **Off** | Socket disattivato | Interfaccia Impostazioni o CMUX\_SOCKET\_MODE=off | | **cmux processes only** | Solo i processi avviati nei terminali cmux possono connettersi. | Modalità predefinita nell'interfaccia Impostazioni | | **allowAll** | Consenti a qualsiasi processo locale di connettersi (nessun controllo di discendenza). | Solo override tramite variabile d'ambiente: CMUX\_SOCKET\_MODE=allowAll | Su macchine condivise, usa Disattivato o Solo processi cmux. ## Opzioni del CLI | Flag | Descrizione | | --- | --- | | `--socket PATH` | Percorso socket personalizzato | | `--json` | Output in formato JSON | | `--window ID` | Specifica una finestra | | `--workspace ID` | Specifica un workspace | | `--surface ID` | Specifica una superficie | | `--id-format refs|uuids|both` | Formato dell'identificatore di controllo nell'output JSON | ## Comandi workspace #### list-workspaces Elenca tutti i workspace aperti. CLI ``` cmux list-workspaces cmux list-workspaces --json ``` Socket ``` {"id":"ws-list","method":"workspace.list","params":{}} ``` #### new-workspace Crea un nuovo workspace. CLI ``` cmux new-workspace ``` Socket ``` {"id":"ws-new","method":"workspace.create","params":{}} ``` #### select-workspace Passa a un workspace specifico. CLI ``` cmux select-workspace --workspace ``` Socket ``` {"id":"ws-select","method":"workspace.select","params":{"workspace_id":""}} ``` #### current-workspace Ottieni il workspace attualmente attivo. CLI ``` cmux current-workspace cmux current-workspace --json ``` Socket ``` {"id":"ws-current","method":"workspace.current","params":{}} ``` #### close-workspace Chiudi un workspace. CLI ``` cmux close-workspace --workspace ``` Socket ``` {"id":"ws-close","method":"workspace.close","params":{"workspace_id":""}} ``` ## Comandi di divisione #### new-split Crea un nuovo pannello diviso. Direzioni: 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 Elenca tutte le superfici nel workspace attuale. CLI ``` cmux list-panels cmux list-panels --json ``` Socket ``` {"id":"surface-list","method":"surface.list","params":{}} ``` #### list-pane-surfaces Elenca le superfici nel pannello attivo. CLI ``` cmux list-pane-surfaces cmux list-pane-surfaces --json ``` Socket ``` {"id":"pane-surfaces","method":"pane.surfaces","params":{}} ``` #### focus-panel Metti a fuoco una superficie specifica. CLI ``` cmux focus-panel --panel ``` Socket ``` {"id":"surface-focus","method":"surface.focus","params":{"surface_id":""}} ``` ## Comandi di input #### send Invia testo al terminale attivo. 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 Invia la pressione di un tasto. Tasti: 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 Invia testo a una superficie specifica. CLI ``` cmux send --surface "command" ``` Socket ``` {"id":"send-surface","method":"surface.send_text","params":{"surface_id":"","text":"command"}} ``` #### send-key --surface Invia la pressione di un tasto a una superficie specifica. CLI ``` cmux send-key --surface enter ``` Socket ``` {"id":"send-key-surface","method":"surface.send_key","params":{"surface_id":"","key":"enter"}} ``` ## Comandi di notifica #### notify Invia una notifica. 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 Elenca tutte le notifiche. CLI ``` cmux list-notifications cmux list-notifications --json ``` Socket ``` {"id":"notif-list","method":"notification.list","params":{}} ``` #### clear-notifications Cancella tutte le notifiche. CLI ``` cmux clear-notifications ``` Socket ``` {"id":"notif-clear","method":"notification.clear","params":{}} ``` ## Comandi metadati della barra laterale Imposta pillole di stato, barre di avanzamento e voci di log nella barra laterale per qualsiasi workspace. Utile per script di build, integrazioni CI e agenti di codice IA che vogliono mostrare lo stato a colpo d'occhio. #### set-status Imposta una pillola di stato nella barra laterale. Usa una chiave univoca così diversi strumenti possono gestire le proprie voci. 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 Rimuovi una voce di stato dalla barra laterale per chiave. CLI ``` cmux clear-status build ``` Socket ``` clear_status build --tab= ``` #### list-status Elenca tutte le voci di stato della barra laterale per un workspace. CLI ``` cmux list-status ``` Socket ``` list_status --tab= ``` #### set-progress Imposta una barra di avanzamento nella barra laterale (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 Cancella la barra di avanzamento della barra laterale. CLI ``` cmux clear-progress ``` Socket ``` clear_progress --tab= ``` #### log Aggiungi una voce di log alla barra laterale. Livelli: 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 Cancella tutte le voci di log della barra laterale. CLI ``` cmux clear-log ``` Socket ``` clear_log --tab= ``` #### list-log Elenca le voci di log della barra laterale. CLI ``` cmux list-log cmux list-log --limit 5 ``` Socket ``` list_log --limit=5 --tab= ``` #### sidebar-state Mostra tutti i metadati della barra laterale (cwd, branch git, porte, stato, avanzamento, log). CLI ``` cmux sidebar-state cmux sidebar-state --workspace workspace:2 ``` Socket ``` sidebar_state --tab= ``` ## Comandi di utilità #### ping Verifica se cmux è in esecuzione e risponde. CLI ``` cmux ping ``` Socket ``` {"id":"ping","method":"system.ping","params":{}} // Response: {"id":"ping","ok":true,"result":{"pong":true}} ``` #### capabilities Elenca i metodi socket disponibili e la modalità di accesso attuale. CLI ``` cmux capabilities cmux capabilities --json ``` Socket ``` {"id":"caps","method":"system.capabilities","params":{}} ``` #### identify Mostra il contesto finestra/workspace/pannello/superficie attivo. CLI ``` cmux identify cmux identify --json ``` Socket ``` {"id":"identify","method":"system.identify","params":{}} ``` ## Variabili d'ambiente | Variabile | Descrizione | | --- | --- | | `CMUX_SOCKET_PATH` | Sovrascrivi il percorso del socket usato dal CLI e dalle integrazioni | | `CMUX_SOCKET_ENABLE` | Forza attivazione/disattivazione del socket (1/0, true/false, on/off) | | `CMUX_SOCKET_MODE` | Sovrascrivi la modalità di accesso (cmuxOnly, allowAll, off). Accetta anche cmux-only/cmux\_only e allow-all/allow\_all | | `CMUX_WORKSPACE_ID` | Auto-impostato: ID del workspace attuale | | `CMUX_SURFACE_ID` | Auto-impostato: ID della superficie attuale | | `TERM_PROGRAM` | Impostato a ghostty | | `TERM` | Impostato a xterm-ghostty | I vecchi valori CMUX\_SOCKET\_MODE full e notifications sono ancora accettati per compatibilità. ## Rilevare 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" ``` ## Esempi ### Client 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 di build con notifica 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/it/docs/api Documentation index: https://cmux.com/llms.txt