# واجهة الأوامر

> ثبّت واجهة الأوامر، وسجّل الدخول بمفتاح واجهة برمجة، وأدِر كل شيء من طرفيّتك.

Source: https://gheima.ma/ar/docs/cli

تتيح لك واجهة أوامر غيمة إدارة حسابك من الطرفية: النشر، وتتبّع السجلات، وإدارة الخدمات وقواعد البيانات والتخزين. تُصادِق بمفتاح API.

### التثبيت وتسجيل الدخول

```bash
npm install -g @gheima/cli
gheima login
```

أو شغّلها دون تثبيت: npx @gheima/cli <command>.

يفتح الأمر gheima login متصفّحك لتوافق على تسجيل الدخول، ثم يحفظ مفتاح API جديدًا في ملف التعريف. على جهاز بلا متصفّح، أضِف ‎--no-browser وافتح الرابط المطبوع بنفسك. من سكربت أو وكيل برمجة لا يستطيع انتظار إدخال، شغّل gheima login ‎--no-wait --json: يطبع الرمز والرابط لتسلّمهما إلى الشخص ثم ينتهي، وبعدها ينتظر gheima login ‎--resume الموافقة ويحفظ المفتاح (أضِف ‎--timeout <ثوانٍ> للعودة لاحقًا؛ يخرج بالرمز 7 ما دام تسجيل الدخول في الانتظار). لاستعمال مفتاح موجود لديك، شغّل gheima login --with-key والصق المفتاح (يبدأ بـ gh_). تُخزَّن المفاتيح لكل ملف تعريف في ~/.config/gheima/config.json بصلاحيات 600. لتخطّي تسجيل الدخول، اضبط متغيّر البيئة GHEIMA_API_KEY.

> Note: تُحدَّد المصادقة بهذا الترتيب: الخيار ‎--key، ثم GHEIMA_API_KEY، ثم ملف التعريف المخزَّن. استعمل ‎--profile <name> للاحتفاظ بمفاتيح منفصلة، مثل مفتاح للعمل وآخر للاستعمال الشخصي. يحذف gheima logout ملف تعريف.

### الخيارات العامة

- `-k, --key <key>`: مفتاح واجهة البرمجة لهذا الاستدعاء (يتجاوز متغيّر البيئة وملف التعريف).
- `-u, --url <url>`: رابط الأساس لواجهة البرمجة (افتراضيًا https://gheima.ma).
- `-p, --profile <name>`: أي ملف تعريف مخزّن يُستخدم.
- `--json`: طباعة JSON قابل للمعالجة بدل جدول.
- `-v, --version`: طباعة إصدار واجهة الأوامر.

### أوامر الحساب

- `gheima login`: تسجيل الدخول عبر المتصفّح أو بمفتاح API موجود، وتخزين المفتاح في ملف تعريف.
- `gheima logout`: حذف ملف تعريف مخزّن.
- `gheima whoami`: عرض حساب المفتاح النشط (الاسم، slug، الخطة، النوع).
- `gheima status`: عرض الحساب والخطة وعدد الخدمات وقواعد البيانات.
- `gheima open [resource]`: فتح لوحة التحكّم (أو مسار) في المتصفّح.
- `gheima completion [shell]`: طباعة سكربت إكمال لـ bash أو zsh أو fish.

### أوامر الخدمة

الأوامر التي تأخذ <service> تقبل معرّفه أو اسمه أو slug الخاص به. تطلب الأوامر المدمّرة تأكيدًا ما لم تمرّر ‎-y أو ‎--yes. وفي طرفية غير تفاعلية، ترفض العمل بدون هذا الخيار.

- `gheima services`: سرد الخدمات. يعادل services list. الأسماء البديلة: service وsvc.
- `gheima services get <id>`: عرض خدمة بالتفصيل.
- `gheima services create --name <name> [--project <id>] [--type WEB|WORKER|STATIC] [--repo <url>]`: إنشاء خدمة. النوع الافتراضي WEB. بدون ‎--project لا تُضاف الخدمة إلى أي مشروع.
- `gheima services delete <id> [-y]`: حذف خدمة.
- `gheima github wait [--repo <url>] [--timeout <minutes>]`: طباعة رابط تثبيت تطبيق Gheima على GitHub لدى مالك هذا المستودع، والانتظار حتى يُثبَّت. يحتاجه مستودع GitHub الخاص ليُبنى؛ يخرج بالرمز 7 إذا انقضت ‎--timeout (عشر دقائق) أولًا.
- `gheima link <service>`: ربط هذا المجلد بخدمة. تستخدم الأوامر التي تُشغَّل فيه، أو في أي مجلد فرعي، تلك الخدمة افتراضيًا.
- `gheima agents [--write]`: يطبع قسمًا قصيرًا للملف AGENTS.md يشرح لوكلاء البرمجة كيف يُنشر هذا المشروع. يضيفه ‎--write‎ إلى الملف مكان أي نسخة سابقة.
- `gheima deploy [service] [--yes] [--upload] [--name <name>] [--type WEB|WORKER|STATIC] [--no-wait] [--timeout <minutes>]`: نشر هذا المجلد، وبثّ عملية البناء، وطباعة الرابط المباشر. يخرج بالرمز 0 عند نجاح النشر، و8 عند فشله. يستخدم الخدمة المرتبطة إن لم تحدّدها. في مجلد بلا خدمة بعد، ينشئ خدمة ويربطها (أكّد بـ ‎--yes حين لا توجد طرفية): تُبنى من مستودع git البعيد إن وُجد، وإلا من ملفات المجلد، تُرفع دون ملفات .env ولا node_modules. يرفع ‎--upload الملفات حتى مع وجود مستودع بعيد.
- `gheima logs <service> [-f] [-b] [-s <text>]`: عرض السجلات أو تتبّعها. ‎-f للتتبّع، و‎-b لسجلات البناء، و‎-s للتصفية بنص.
- `gheima run <service> [--timeout <seconds>] [--no-wait] -- <command>`: تشغيل أمر لمرة واحدة، مثل ترحيل قاعدة البيانات، في حاوية جديدة من الصورة المنشورة للخدمة وبيئتها. يعرض سجلّه ويخرج برمز خروج الأمر، أو 9 إن لم يُرجع أيّ رمز. للمسؤولين فقط. تُضمّ الكلمات ويشغّلها الـshell البعيد، لذا ضع الأمر كاملًا بين علامتي اقتباس إذا احتوى أحد وسائطه على مسافات، مثل gheima run web -- 'psql -c "select 1"'.
- `gheima env ls [service]`: سرد مفاتيح المتغيّرات بقيم مقنّعة.
- `gheima env pull [service] [--file <path>] [-f] [--stdout]`: كتابة قيم متغيّرات الخدمة كنص صريح في ‎.env.local (بالصلاحيات 0600). لا يمكن قراءة المتغيّرات السرّية، لذا لا تُكتب.
- `gheima env push [service] [--file <path>] [--replace] [-y]`: رفع ملف ‎.env إلى الخدمة. يدمج افتراضيًا؛ ويحذف ‎--replace المتغيّرات غير الموجودة في الملف.
- `gheima env set <service> KEY=value`: ضبط متغيّر بيئة.
- `gheima env rm <service> <key> [-y]`: حذف متغيّر بيئة.
- `gheima domains <service>`: سرد النطاقات المخصّصة لخدمة.

### أوامر الموارد

- `gheima db`: سرد قواعد البيانات. الاسم البديل: databases.
- `gheima storage buckets`: سرد حاويات تخزين الكائنات.
- `gheima storage ls <bucket> [prefix]`: سرد كائنات حاوية.
- `gheima storage cp <file> <bucket> [key]`: رفع ملف محلي عبر رابط موقّع مسبقًا.
- `gheima storage get <bucket> <key> [dest]`: تنزيل كائن.
- `gheima storage rm <bucket> <key> [-y]`: حذف كائن.
- `gheima cron`: سرد مهام كرون.
- `gheima webhooks`: سرد خطافات الويب.

```bash
gheima services create --name web --type WEB --repo https://github.com/me/app
gheima deploy web
gheima logs web -f -s error
gheima env set web NODE_ENV=production
gheima storage cp ./photo.png my-bucket images/photo.png
gheima services --json | jq '.[].url'
```

جلسة نموذجية. أضِف --json إلى أي أمر لمخرجات منظّمة.

> Result: تغطي واجهة الأوامر كل عمليات API، فيمكنك برمجة النشر والسجلات وإدارة الموارد من الطرفية.

---

All docs: https://gheima.ma/ar/docs.md