Référence API

cmux fournit à la fois un outil CLI et un socket Unix pour le contrôle programmatique. Chaque commande est disponible via les deux interfaces.

Socket

Build	Chemin
Release	`/tmp/cmux.sock`
Debug	`/tmp/cmux-debug.sock`
Build debug tagué	`/tmp/cmux-debug-<tag>.sock`

Remplacez avec la variable d'environnement CMUX_SOCKET_PATH. Envoyez une requête JSON terminée par un retour à la ligne par appel :

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

Les requêtes JSON du socket doivent utiliser method et params. Les anciens payloads JSON v1 comme {"command":"..."} ne sont pas supportés.

Modes d'accès

Mode	Description	Comment activer
Off	Socket désactivé	Interface Réglages ou CMUX_SOCKET_MODE=off
cmux processes only	Seuls les processus démarrés dans les terminaux cmux peuvent se connecter.	Mode par défaut dans l'interface Réglages
allowAll	Autoriser tout processus local à se connecter (pas de vérification d'ascendance).	Remplacement par variable d'environnement uniquement : CMUX_SOCKET_MODE=allowAll

Sur les machines partagées, utilisez Désactivé ou Processus cmux uniquement.

Options du CLI

Option	Description
`--socket PATH`	Chemin de socket personnalisé
`--json`	Sortie au format JSON
`--window ID`	Cibler une fenêtre spécifique
`--workspace ID`	Cibler un espace de travail spécifique
`--surface ID`	Cibler une surface spécifique
`--id-format refs\|uuids\|both`	Format d'identifiant de contrôle dans la sortie JSON

Commandes d'espace de travail

list-workspaces

Lister tous les espaces de travail ouverts.

CLI

cmux list-workspaces
cmux list-workspaces --json

Socket

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

new-workspace

Créer un nouvel espace de travail.

CLI

cmux new-workspace

Socket

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

select-workspace

Basculer vers un espace de travail spécifique.

CLI

cmux select-workspace --workspace <id>

Socket

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

current-workspace

Obtenir l'espace de travail actuellement actif.

CLI

cmux current-workspace
cmux current-workspace --json

Socket

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

close-workspace

Fermer un espace de travail.

CLI

cmux close-workspace --workspace <id>

Socket

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

Commandes de division

new-split

Créer un nouveau panneau divisé. Directions : 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

Lister toutes les surfaces dans l'espace de travail actuel.

CLI

cmux list-surfaces
cmux list-surfaces --json

Socket

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

focus-surface

Mettre le focus sur une surface spécifique.

CLI

cmux focus-surface --surface <id>

Socket

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

Commandes de saisie

send

Envoyer du texte au terminal actif.

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

Envoyer une touche. Touches : 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

Envoyer du texte à une surface spécifique.

CLI

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

Socket

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

send-key-surface

Envoyer une touche à une surface spécifique.

CLI

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

Socket

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

Commandes de notification

notify

Envoyer une notification.

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

Lister toutes les notifications.

CLI

cmux list-notifications
cmux list-notifications --json

Socket

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

clear-notifications

Effacer toutes les notifications.

CLI

cmux clear-notifications

Socket

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

Commandes de métadonnées de la barre latérale

Définir des pastilles de statut, barres de progression et entrées de journal dans la barre latérale pour n'importe quel espace de travail. Utile pour les scripts de build, intégrations CI et agents de code IA qui souhaitent afficher l'état en un coup d'œil.

set-status

Définir une pastille de statut dans la barre latérale. Utilisez une clé unique pour que différents outils puissent gérer leurs propres entrées.

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

Supprimer une entrée de statut de la barre latérale par clé.

CLI

cmux clear-status build

Socket

clear_status build --tab=<workspace-uuid>

list-status

Lister toutes les entrées de statut de la barre latérale pour un espace de travail.

CLI

cmux list-status

Socket

list_status --tab=<workspace-uuid>

set-progress

Définir une barre de progression dans la barre latérale (0.0 à 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

Effacer la barre de progression de la barre latérale.

CLI

cmux clear-progress

Socket

clear_progress --tab=<workspace-uuid>

log

Ajouter une entrée de journal à la barre latérale. Niveaux : 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

Effacer toutes les entrées de journal de la barre latérale.

CLI

cmux clear-log

Socket

clear_log --tab=<workspace-uuid>

list-log

Lister les entrées de journal de la barre latérale.

CLI

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

Socket

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

sidebar-state

Afficher toutes les métadonnées de la barre latérale (cwd, branche git, ports, statut, progression, journaux).

CLI

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

Socket

sidebar_state --tab=<workspace-uuid>

Commandes utilitaires

ping

Vérifier si cmux fonctionne et répond.

CLI

cmux ping

Socket

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

capabilities

Lister les méthodes socket disponibles et le mode d'accès actuel.

CLI

cmux capabilities
cmux capabilities --json

Socket

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

identify

Afficher le contexte fenêtre/espace de travail/panneau/surface actif.

CLI

cmux identify
cmux identify --json

Socket

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

Variables d'environnement

Variable	Description
`CMUX_SOCKET_PATH`	Remplacer le chemin du socket utilisé par le CLI et les intégrations
`CMUX_SOCKET_ENABLE`	Forcer l'activation/désactivation du socket (1/0, true/false, on/off)
`CMUX_SOCKET_MODE`	Remplacer le mode d'accès (cmuxOnly, allowAll, off). Accepte aussi cmux-only/cmux_only et allow-all/allow_all
`CMUX_WORKSPACE_ID`	Auto-défini : ID de l'espace de travail actuel
`CMUX_SURFACE_ID`	Auto-défini : ID de la surface actuelle
`TERM_PROGRAM`	Défini à ghostty
`TERM`	Défini à xterm-ghostty

Les anciennes valeurs CMUX_SOCKET_MODE full et notifications sont toujours acceptées pour compatibilité.

Détecter 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"

Exemples

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 de build avec notification

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