# Довідник CLI

cmux надає і CLI-інструмент, і Unix-сокет для програмного керування. Кожна команда доступна через обидва інтерфейси.

## Сокет

| Збірка | Шлях |
| --- | --- |
| Релізна збірка | `/tmp/cmux.sock` |
| Налагоджувальна збірка | `/tmp/cmux-debug.sock` |
| Налагоджувальна збірка з тегом | `/tmp/cmux-debug-<tag>.sock` |

Перевизначте за допомогою змінної середовища CMUX\_SOCKET\_PATH. Надсилайте один JSON-запит, завершений символом нового рядка, за виклик:

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

JSON-запити до сокета мають використовувати method і params. Застарілі JSON-повідомлення v1, як-от `{"command":"..."}`, не підтримуються.

## Режими доступу

| Режим | Опис | Як увімкнути |
| --- | --- | --- |
| **Off** | Сокет вимкнено | Інтерфейс налаштувань або CMUX\_SOCKET\_MODE=off |
| **cmux processes only** | Підключатися можуть лише процеси, запущені в терміналах cmux. | Режим за замовчуванням в інтерфейсі налаштувань |
| **allowAll** | Дозволити підключення будь-якому локальному процесу (без перевірки походження). | Вмикається тільки змінною середовища: CMUX\_SOCKET\_MODE=allowAll |

На спільних комп'ютерах використовуйте режим «Off» або «cmux processes only».

## Параметри CLI

| Прапорець | Опис |
| --- | --- |
| `--socket PATH` | Власний шлях до сокета |
| `--json` | Вивести у форматі JSON |
| `--window ID` | Вибрати певне вікно |
| `--workspace ID` | Вибрати певний робочий простір |
| `--surface ID` | Вибрати певну поверхню |
| `--id-format refs|uuids|both` | Формат ідентифікаторів у JSON-виводі |

## Команди робочих просторів

#### list-workspaces

Показати всі відкриті робочі простори.

CLI

```
cmux list-workspaces
cmux list-workspaces --json
```

Socket

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

#### new-workspace

Створити новий робочий простір.

CLI

```
cmux new-workspace
```

Socket

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

#### select-workspace

Перейти до певного робочого простору.

CLI

```
cmux select-workspace --workspace <id>
```

Socket

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

#### current-workspace

Повертає робочий простір, який зараз активний.

CLI

```
cmux current-workspace
cmux current-workspace --json
```

Socket

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

#### close-workspace

Закрити робочий простір.

CLI

```
cmux close-workspace --workspace <id>
```

Socket

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

## Команди розділення

#### new-split

Створити нову розділену панель. Напрямки: left, right, up, down. Передайте --command <text>, щоб запустити команду в новій оболонці термінала; оболонка залишиться відкритою після завершення команди.

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

Показати список усіх поверхонь у поточному робочому просторі.

CLI

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

Socket

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

#### list-pane-surfaces

Показати список поверхонь в активній панелі.

CLI

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

Socket

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

#### focus-panel

Сфокусувати певну поверхню.

CLI

```
cmux focus-panel --panel <id>
```

Socket

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

## Команди введення

#### send

Надіслати текстове введення до сфокусованого термінала.

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

Надсилає одне натискання клавіші. Доступні клавіші: 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

Надіслати текст до певної поверхні.

CLI

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

Socket

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

#### send-key --surface

Надіслати натискання клавіші до певної поверхні.

CLI

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

Socket

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

## Команди сповіщень

#### notify

Надіслати сповіщення.

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

Показати всі сповіщення.

CLI

```
cmux list-notifications
cmux list-notifications --json
```

Socket

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

#### clear-notifications

Очистити всі сповіщення.

CLI

```
cmux clear-notifications
```

Socket

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

## Команди метаданих бічної панелі

Установлюйте плашки статусу, індикатори прогресу й записи журналу в бічній панелі для будь-якого робочого простору. Корисно для скриптів збірки, інтеграцій CI та AI-агентів для програмування, які хочуть показувати стан з першого погляду.

#### set-status

Установити плашку статусу в бічній панелі. Використовуйте унікальний ключ, щоб різні інструменти могли керувати власними записами.

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

Видалити запис статусу з бічної панелі за ключем.

CLI

```
cmux clear-status build
```

Socket

```
clear_status build --tab=<workspace-uuid>
```

#### list-status

Показати всі записи статусу бічної панелі для робочого простору.

CLI

```
cmux list-status
```

Socket

```
list_status --tab=<workspace-uuid>
```

#### set-progress

Установити індикатор прогресу в бічній панелі (від 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

Прибрати індикатор прогресу з бічної панелі.

CLI

```
cmux clear-progress
```

Socket

```
clear_progress --tab=<workspace-uuid>
```

#### log

Додає рядок журналу на бічну панель. Доступні рівні: 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

Очистити всі записи журналу в бічній панелі.

CLI

```
cmux clear-log
```

Socket

```
clear_log --tab=<workspace-uuid>
```

#### list-log

Показати записи журналу бічної панелі.

CLI

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

Socket

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

#### sidebar-state

Вивести всі метадані бічної панелі (cwd, гілка git, порти, статус, прогрес, журнали).

CLI

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

Socket

```
sidebar_state --tab=<workspace-uuid>
```

## Службові команди

#### ping

Перевірити, чи cmux запущено і чи він відповідає.

CLI

```
cmux ping
```

Socket

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

#### capabilities

Показати доступні методи сокета та поточний режим доступу.

CLI

```
cmux capabilities
cmux capabilities --json
```

Socket

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

#### identify

Показати контекст сфокусованого вікна, робочого простору, панелі та поверхні.

CLI

```
cmux identify
cmux identify --json
```

Socket

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

## Змінні середовища

| Змінна | Опис |
| --- | --- |
| `CMUX_SOCKET_PATH` | Перевизначити шлях до сокета, який використовують CLI та інтеграції |
| `CMUX_SOCKET_ENABLE` | Примусово ввімкнути або вимкнути сокет (1/0, true/false, on/off) |
| `CMUX_SOCKET_MODE` | Перевизначити режим доступу (cmuxOnly, allowAll, off). Також приймаються cmux-only/cmux\_only і allow-all/allow\_all |
| `CMUX_WORKSPACE_ID` | Установлюється автоматично: ID поточного робочого простору |
| `CMUX_SURFACE_ID` | Установлюється автоматично: ID поточної поверхні |
| `TERM_PROGRAM` | Установлюється в ghostty |
| `TERM` | Установлюється в xterm-ghostty |

Застарілі значення CMUX\_SOCKET\_MODE full і notifications досі приймаються для сумісності.

## Виявлення 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"
```

## Приклади

### Клієнт на 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"
))
```

### Скрипт оболонки

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"}}'
```

### Скрипт збірки зі сповіщенням

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/uk/docs/api

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