مرجع الواجهة البرمجية

يوفر 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

Socket

{"id":"split-new","method":"surface.split","params":{"direction":"right"}}

list-surfaces

عرض جميع الأسطح في مساحة العمل الحالية.

CLI

cmux list-surfaces
cmux list-surfaces --json

Socket

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

focus-surface

التركيز على سطح محدد.

CLI

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

Socket

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