# مرجع CLI

## الاستخدام الأساسي

شغّل الأمر فحسب، دون الحاجة إلى وسائط:

```bash
npx termbridge
```

يبدأ هذا كل شيء: الخادم المحلي وجلسة tmux ونفق Cloudflare الافتراضي.

تشغيل `termbridge` بلا أمر فرعي يعادل `termbridge start`.

يمكنك أيضًا تشغيل `termbridge start` صراحةً مع جميع العلامات:

```bash
termbridge start --port 8080 --proxy 5173 --session dev --kill-on-exit --no-qr --tunnel cloudflare
```

## العلامات

| العلامة | وظيفتها | الافتراضي |
|------|--------------|---------|
| `--port <port>` | استخدام منفذ محدد بدلًا من منفذ عشوائي | عشوائي |
| `--proxy <port>` | تمرير خادم تطوير محلي عبر الوكيل (يتيح عرضي الطرفية والمعاينة) | - |
| `--session <name>` | تسمية جلسة tmux | يُنشأ تلقائيًا |
| `--kill-on-exit` | تنظيف جلسات tmux عند خروج Termbridge | إيقاف |
| `--no-qr` | عدم طباعة رمز QR (مفيد للنصوص البرمجية) | إيقاف |
| `--no-tunnel` | تعطيل النفق (يتطلب `--public-url`) | إيقاف |
| `--public-url <url>` | URL عام عند تعطيل النفق | - |
| `--tunnel <provider>` | موفر النفق (`cloudflare` أو `none`) | cloudflare |
| `--tunnel-token <token>` | استخدام رمز نفق Cloudflare مسمى (يتطلب `--port`) | - |
| `--tunnel-url <url>` | URL عام للنفق المسمى (مطلوب مع `--tunnel-token`) | - |
| `--backend <backend>` | واجهة الطرفية الخلفية (`tmux` أو `sandbox-daytona`) | tmux |
| `--sandbox-repo <url>` | URL المستودع المراد استنساخه إلى بيئة Daytona المعزولة | - |
| `--sandbox-branch <branch>` | الفرع المراد سحبه في البيئة المعزولة | - |
| `--sandbox-path <path>` | مسار المستودع في البيئة المعزولة | مشتق من اسم المستودع |
| `--sandbox-name <name>` | اسم البيئة المعزولة | `termbridge-<hex>` عشوائي |
| `--sandbox-preview-port <port>` | منفذ المعاينة في البيئة المعزولة | - |
| `--sandbox-public` | إنشاء بيئة معزولة عامة | إيقاف (تشغيل في الوضع المباشر) |
| `--sandbox-direct` | تشغيل الخادم داخل بيئة Daytona المعزولة (بلا نفق) | إيقاف |
| `--dev-proxy-url <url>` | تمرير حركة المعاينة إلى URL هذا بدلًا من `localhost:<proxy port>` (تستخدمه نصوص التطوير) | - |
| `-h`، `--help` | طباعة نص المساعدة | - |

أي خيار آخر يؤدي إلى `unknown option: <flag>`. لا توجد علامة `--version`.

تتقدم العلامة على متغير البيئة المقابل لها، باستثناء واحد: يتجاوز `TERMBRIDGE_TUNNEL` حاليًا `--tunnel` و`--no-tunnel` ([#5](https://github.com/inline0/termbridge/issues/5)).

> **ملاحظة**
> لا يزال ناتج المساعدة المضمّن في `termbridge --help` يسرد علامات `--daytona-*` و`--backend tmux | daytona`. تُرفض هذه الأسماء؛ استخدم العلامات `--sandbox-*` و`--backend sandbox-daytona` الواردة في الجدول أعلاه ([#1](https://github.com/inline0/termbridge/issues/1)).

## أمثلة

### الاتصال بجلسة tmux موجودة

إذا كانت لديك جلسة tmux قيد التشغيل بالفعل:

```bash
termbridge --session my-session
```

### منفذ ثابت وجلسة مخصصة

```bash
termbridge --port 8080 --session codex
```

### خروج نظيف (بلا جلسات متبقية)

```bash
termbridge --kill-on-exit
```

### البرمجة النصية (بلا ناتج QR)

```bash
termbridge --no-qr
```

### تمرير خادم تطوير Vite عبر الوكيل

```bash
# Start your Vite app first
cd my-app && npm run dev  # runs on port 5173

# Then start Termbridge with proxy
termbridge --proxy 5173
```

استخدم زر **العروض** للتبديل بين الطرفية والمعاينة. تحمّل المعاينة تطبيقك عبر الوكيل مع دعم HMR.

### نفق Cloudflare مسمى (باستخدام رمز)

إذا كان لديك حساب Cloudflare وتريد تجنب حدود المعدل في trycloudflare:

```bash
termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com
```

### تعطيل النفق (توفير URL عام خاص بك)

```bash
termbridge --no-tunnel --public-url https://example.com
```

## متغيرات البيئة

يقرأ Termbridge متغيرات البيئة من الصدفة ومن ملف `.env` في المجلد الذي تشغّله منه. تكون الأولوية للمتغيرات المعينة في الصدفة على متغيرات ملف `.env`.

### الإعدادات الأساسية

| المتغير | وظيفته |
|----------|--------------|
| `TERMBRIDGE_SESSIONS=2` | إنشاء جلسات tmux متعددة عند بدء التشغيل |
| `TERMBRIDGE_TMUX_CWD=/path` | مجلد العمل لجلسات tmux الجديدة |
| `TERMBRIDGE_PUBLIC_URL=https://example.com` | URL عام عند تعطيل النفق |
| `TERMBRIDGE_TUNNEL=none` | تعطيل النفق |
| `TERMBRIDGE_TUNNEL_TOKEN=<token>` | رمز النفق المسمى (يتطلب `TERMBRIDGE_TUNNEL_URL`) |
| `TERMBRIDGE_TUNNEL_URL=https://term.example.com` | URL عام للنفق المسمى |

### متقدم

يضبط وضع Daytona المباشر هذه المتغيرات للخادم الذي يشغّله داخل البيئة المعزولة. ويمكنك ضبطها بنفسك أيضًا.

| المتغير | وظيفته |
|----------|--------------|
| `TERMBRIDGE_HOST=0.0.0.0` | العنوان الذي يرتبط به الخادم (الافتراضي `127.0.0.1`). يعرض URL المحلي المطبوع دائمًا `127.0.0.1`. |
| `TERMBRIDGE_COOKIE_SAMESITE=lax` | قيمة `SameSite` لملف تعريف ارتباط الجلسة: `lax` أو `strict` أو `none` (الافتراضي `Lax`، أو `None` في الوضع المباشر) |
| `TERMBRIDGE_SHARE_FILE=/path/share-url.txt` | اكتب أيضًا مشاركة URL في هذا الملف |
| `TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1` | أخفِ مبدّل الطرفية في UI |
| `TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin` | أضف هذا في بداية `PATH` في كل جلسة tmux يبدأها Termbridge أو يتصل بها (يُكتب في الجلسة كأمر `export`) |

### التطوير

| المتغير | وظيفته |
|----------|--------------|
| `TERMBRIDGE_INSECURE_COOKIE=1` | السماح بملفات تعريف ارتباط HTTP (للتطوير المحلي فقط) |
| `TERMBRIDGE_PROXY_PORT=5173` | منفذ الوكيل لبرنامج dev:beam:proxy النصي |
| `TERMBRIDGE_DEV_UI=http://127.0.0.1:5000` | تجاوز UI تطوير Vite URL |
| `TERMBRIDGE_DEV_PORT=3000` | تجاوز منفذ خادم Termbridge في وضع التطوير (الافتراضي `8787`) |
| `TERMBRIDGE_DEV_SESSION=codex` | اسم جلسة tmux لـ `dev:beam` (الافتراضي `codex`) |
| `TERMBRIDGE_SKIP_BUILD=1` | تخطَّ بناء CLI في `dev:beam` |

### البيئة المعزولة (Daytona)

| المتغير | وظيفته |
|----------|--------------|
| `TERMBRIDGE_BACKEND=sandbox-daytona` | استخدام الواجهة الخلفية للبيئة المعزولة في Daytona |
| `TERMBRIDGE_SANDBOX_DIRECT=true` | تشغيل Termbridge داخل البيئة المعزولة |
| `TERMBRIDGE_SANDBOX_SERVER_PORT=8080` | منفذ الخادم داخل البيئة المعزولة |
| `TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex` | تثبيت تلقائي ومزامنة المصادقة للوكلاء |
| `TERMBRIDGE_SANDBOX_AGENT_ENV=...` | متغيرات بيئة إضافية لتمريرها |
| `TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=...` | ملفات المصادقة المحلية لمزامنتها |

للاطلاع على إعداد Daytona الكامل، راجع [دليل Daytona](https://termbridge.inline0.dev/ar/docs/sandboxes/daytona).

## إيقاف Termbridge

اضغط على `Ctrl+C` في الطرفية التي يعمل فيها Termbridge. وسيؤدي ذلك إلى:

- إغلاق النفق (إن كان مفعّلًا)
- إيقاف الخادم المحلي
- إبقاء جلسات tmux قيد التشغيل (إلا إذا استخدمت `--kill-on-exit`)

تظل جلسات tmux قيد التشغيل افتراضيًا، لذا يمكنك إعادة الاتصال لاحقًا.