# Référence CLI

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
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

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

CLI

```
cmux list-panels
cmux list-panels --json
```

Socket

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

#### list-pane-surfaces

Lister les surfaces du panneau actif.

CLI

```
cmux list-pane-surfaces
cmux list-pane-surfaces --json
```

Socket

```
{"id":"pane-surfaces","method":"pane.surfaces","params":{}}
```

#### focus-panel

Mettre le focus sur une surface spécifique.

CLI

```
cmux focus-panel --panel <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 <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 <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" --priority 80
cmux set-status deploy "v1.2.3" --workspace workspace:2
```

Socket

```
set_status build compiling --icon=hammer --color=#ff9500 --priority=80 --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
```

Canonical: https://cmux.com/fr/docs/api

Documentation index: https://cmux.com/llms.txt