# مرجع CLI

يوفر cmux أداة سطر أوامر ومقبس 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 |

على الأجهزة المشتركة، استخدم وضع معطل أو عمليات cmux فقط.

## خيارات واجهة الأوامر

| العلم | الوصف |
| --- | --- |
| `--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

إنشاء لوح مقسم جديد. الاتجاهات: يسار، يمين، أعلى، أسفل.

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 ووكلاء البرمجة بالذكاء الاصطناعي التي تريد إظهار الحالة بنظرة سريعة.

#### 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` | تجاوز مسار المقبس المستخدم بواسطة واجهة الأوامر والتكاملات |
| `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` | يُعين تلقائياً: معرف مساحة العمل الحالية |
| `CMUX_SURFACE_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"
))
```

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

### نص بناء مع إشعار

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

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