Commandes personnalisées

Définissez des commandes personnalisées et des mises en page d'espace de travail en ajoutant un fichier cmux.json à la racine de votre projet ou ~/.config/cmux/. Les commandes apparaissent dans la palette de commandes.

Emplacements des fichiers

cmux recherche la configuration à deux endroits :

Par projet : ./cmux.json — se trouve dans votre répertoire de projet, a la priorité
Global : ~/.config/cmux/cmux.json — s'applique à tous les projets, complète les commandes non définies localement

Les commandes locales remplacent les commandes globales du même nom.

Les modifications sont prises en compte automatiquement — aucun redémarrage nécessaire.

Schéma

Un fichier cmux.json contient un tableau commands. Chaque commande est soit une commande shell simple, soit une définition complète d'espace de travail :

cmux.json

{
  "commands": [
    {
      "name": "Start Dev",
      "keywords": ["dev", "start"],
      "workspace": { ... }
    },
    {
      "name": "Run Tests",
      "command": "npm test",
      "confirm": true
    }
  ]
}

Commandes simples

Une commande simple exécute une commande shell dans le terminal actuellement focalisé :

cmux.json

{
  "commands": [
    {
      "name": "Run Tests",
      "keywords": ["test", "check"],
      "command": "npm test",
      "confirm": true
    }
  ]
}

Champs

name — Affiché dans la palette de commandes (requis)
description — Description optionnelle
keywords — Termes de recherche supplémentaires pour la palette de commandes
command — Commande shell à exécuter dans le terminal focalisé
confirm — Afficher une boîte de dialogue de confirmation avant l'exécution

Les commandes simples s'exécutent dans le répertoire de travail actuel du terminal ciblé. Si votre commande utilise des chemins relatifs au projet, préfixez avec cd "$(git rev-parse --show-toplevel)" && pour exécuter depuis la racine du dépôt, ou cd /your/path && pour n'importe quel répertoire spécifique.

Commandes d'espace de travail

Une commande d'espace de travail crée un nouvel espace de travail avec une mise en page personnalisée de divisions, terminaux et panneaux de navigateur :

cmux.json

{
  "commands": [
    {
      "name": "Dev Environment",
      "keywords": ["dev", "fullstack"],
      "restart": "confirm",
      "workspace": {
        "name": "Dev",
        "cwd": ".",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Frontend",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Backend",
                    "command": "cargo watch -x run",
                    "cwd": "./server",
                    "env": { "RUST_LOG": "debug" }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

Champs de l'espace de travail

name — Nom de l'onglet de l'espace de travail (par défaut, nom de la commande)
cwd — Répertoire de travail de l'espace de travail
color — Couleur de l'onglet de l'espace de travail
layout — Arbre de mise en page définissant les divisions et panneaux

Comportement au redémarrage

Contrôle ce qui se passe lorsqu'un espace de travail du même nom existe déjà :

"ignore" — Basculer vers l'espace de travail existant (par défaut)
"recreate" — Fermer et recréer sans demander
"confirm" — Demander à l'utilisateur avant de recréer

Arbre de mise en page

L'arbre de mise en page définit comment les panneaux sont disposés à l'aide de nœuds de division récursifs :

Nœud de division

Divise l'espace en deux enfants :

direction — "horizontal" ou "vertical"
split — Position du séparateur de 0.1 à 0.9 (par défaut 0.5)
children — Exactement deux nœuds enfants (division ou panneau)

Nœud de panneau

Un nœud feuille contenant une ou plusieurs surfaces (onglets dans le panneau).

Définition de surface

Chaque surface dans un panneau peut être un terminal ou un navigateur :

type — "terminal" ou "browser"
name — Titre d'onglet personnalisé
command — Commande shell à exécuter automatiquement à la création (terminal uniquement)
cwd — Répertoire de travail pour cette surface
env — Variables d'environnement sous forme de paires clé-valeur
url — URL à ouvrir (navigateur uniquement)
focus — Focaliser cette surface après la création

Résolution du répertoire de travail

. ou omis — répertoire de travail de l'espace de travail
./subdir — relatif au répertoire de travail de l'espace de travail
~/path — développé vers le répertoire personnel
Chemin absolu — utilisé tel quel

Exemple complet

cmux.json

{
  "commands": [
    {
      "name": "Web Dev",
      "description": "Docs site with live preview",
      "keywords": ["web", "docs", "next", "frontend"],
      "restart": "confirm",
      "workspace": {
        "name": "Web Dev",
        "cwd": "./web",
        "color": "#3b82f6",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Next.js",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.6,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "browser",
                        "name": "Preview",
                        "url": "http://localhost:3777"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": { "NODE_ENV": "development" }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "name": "Debug Log",
      "description": "Tail the debug event log from the running dev app",
      "keywords": ["log", "debug", "tail", "events"],
      "restart": "ignore",
      "workspace": {
        "name": "Debug Log",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Events",
                    "command": "tail -f /tmp/cmux-debug.log",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Shell"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Setup",
      "description": "Initialize submodules and build dependencies",
      "keywords": ["setup", "init", "install"],
      "command": "./scripts/setup.sh",
      "confirm": true
    },
    {
      "name": "Reload",
      "description": "Build and launch the debug app tagged to the current branch",
      "keywords": ["reload", "build", "run", "launch"],
      "command": "./scripts/reload.sh --tag $(git branch --show-current)"
    },
    {
      "name": "Run Unit Tests",
      "keywords": ["test", "unit"],
      "command": "./scripts/test-unit.sh",
      "confirm": true
    }
  ]
}