`cmp` أداة سطر الأوامر

أين في البوابة: أوامر التثبيت موجودة في مرجع الAPI (https://<your-domain>/apidoc، قسم Command-line interface). الموافقة على تسجيل الدخول: https://<your-domain>/link. الأجهزة المتصلة: API keys (/api-keys) › Connected apps & devices.

الوظيفة

cmp هو برنامج صغير بسطر الأوامر لعملائك (ولك) والذي يحول كل عملية API إلى أمر: cmp vm list، cmp vm start <id>، cmp billing invoice list. تم بناؤه من مستند OpenAPI الخاص بتثبيتك الخاص في وقت الإصدار، لذا تتطابق الأوامر مع الميزات التي قمت بتفعيلها. إنه ملف ثنائي ثابت واحد لنظام Linux وmacOS وWindows (amd64 وarm64) مع عدم وجود أي شيء آخر لتثبيته.

المتطلبات

العنصر	المتطلب
الخادم	لا شيء إضافي. حزم الإصدار موجودة داخل إصدار NexCMP ويتم تقديمها بواسطة اللوحة في `https://<your-domain>/cli/`.
جهاز العميل	Linux أو macOS أو Windows (PowerShell 5.1+). يلزم وجود `ssh-keygen` (OpenSSH 8.0+) فقط للتحقق من التوقيع.
بيانات الاعتماد	تسجيل دخول عبر المتصفح برمز لمرة واحدة، أو مفتاح API.
الشبكة	بروتوكول HTTPS للوحتك. ترفض أداة CLI إرسال مفتاح عبر بروتوكول `http://` العادي إلا إلى `localhost`.

تجهيز البنية التحتية

لا شيء. تقوم اللوحة بتقديم هذه الملفات من /cli/ (لا يلزم بناء أو رفع):

الملف	الغرض
`install.sh`, `install.ps1`	برامج التثبيت لنظام Linux/macOS وWindows؛ وهي تحتوي على عنوان لوحتك.
`latest.json`	الإصدار الحالي، قائمة الملفات، الأحجام، وsha256.
`v<version>/cmp_<version>_<os>_<arch>.tar.gz` أو `.zip`	البرامج: linux amd64/arm64، darwin amd64/arm64/universal، windows amd64/arm64.
`v<version>/SHA256SUMS`, `SHA256SUMS.sig`	المجاميع الاختبارية وتوقيع ed25519 الخاص بها.
`cmp-cli.pub`	المفتاح العام للإصدار.

التثبيت (للعميل)

أنظمة macOS وLinux:

bash

curl -fsSL https://cloud.example.com/cli/install.sh | sh

برنامج PowerShell لنظام Windows:

powershell

irm https://cloud.example.com/cli/install.ps1 | iex

يختار برنامج التثبيت الحزمة الخاصة بنظام التشغيل وحدة المعالجة المركزية، ويقوم بتنزيل SHA256SUMS وتوقيعه، والتحقق من التوقيع باستخدام المفتاح المضمن في البرنامج النصي، والتحقق من تجزئة الحزمة، وتثبيت cmp في /usr/local/bin (بصفتك root) أو ~/.local/bin؛ وعلى نظام Windows في %LOCALAPPDATA%\cmp\bin (المضاف إلى PATH للمستخدم). إذا فشل أي تحقق فللن يتم تثبيت أي شيء.

المتغير	المعنى
`CMP_VERSION`	تثبيت هذا الإصدار بدلاً من أحدث إصدار.
`CMP_INSTALL_DIR`	مجلد التثبيت.
`CMP_REQUIRE_SIGNATURE`	`1` = الإلغاء عندما تعذر التحقق من التوقيع.
`CMP_BASE_URL`	قاعدة التنزيل (للمرايا).

التنزيل اليدوي والتحقق:

bash

curl -fsSLO https://cloud.example.com/cli/latest.json
sha256sum --check --ignore-missing SHA256SUMS

تطبع أداة CLI رمْزاً لمرة واحدة ورابطاً (https://cloud.example.com/link?code=WDJB-MJHT)، وتفتح المتصفح وتنتظر.
في المتصفح، قم بتسجيل الدخول إلى البوابة، وافحص اسم العميل، والجهاز، وعنوان IP والبلد، وحدد الأذونات (النطاقات) واتركه يحدد مدة صلاحية المفتاح (الافتراضي 90 يوماً). الأذونات التي تكلف أموالاً أو تحذف بيانات تبدأ بدون تحديد. انقر فوق موافق.
تتلقى أداة CLI مفتاحها الخاص، منفصلاً عن المفاتيح التي أنشأها العميل يدويًا، وتقوم بتخزينه في ~/.config/cmp/config.json (الوضع 0600؛ %APPDATA%\cmp على نظام Windows). يظهر تحت API keys › Connected apps & devices ويمكن إلغاؤه من هناك.

ينتهي صلاحية الرمز بعد 10 دقائق. تتطلب الموافقة جلسة بوابة حقيقية مسجلة الدخول مع بريد إلكتروني متحقق منه — وليس مفتاحًا آخر وليست جلسة منتحلة.

شارات مفيدة: --scopes vm:read,billing:read، --name "build server"، --no-browser، --profile، --api-url.

بالنسبة لـ CI أو الخوادم التي ليس لها متصفح، استخدم مفتاحاً من البوابة:

bash

printf %s "$KEY" | cmp login --with-token
export CMP_TOKEN=vk_XXXX      # nothing is written to disk
cmp whoami

استخدام الأوامر

text

cmp <group> [subgroup] <action> [<id> ...] [flags]

معلمات المسار هي وسائط موضعية؛ وتصبح معلمات الاستعلام وحقول الجسم شارات بصيغة kebab-case (--start-port 443).
ترسل --data '{"a":1}' أو --data @file.json أو --data - محتوى JSON كاملاً؛ وتتجاوز الخيارات (flags) حقوله.
يعرض cmp help vm firewall add (أو --help) تفاصيل أي أمر.

bash

cmp catalog plans
cmp vm list --state active --per-page 50
cmp vm get 3f2a1c9e-0000-4000-8000-000000000000
cmp vm start 3f2a1c9e-0000-4000-8000-000000000000
cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24
cmp billing wallet
cmp api GET /v1/vm --query page=2      # raw call to any endpoint

الأوامر المضمنة: login وlogout وwhoami وconfig وapi وcompletion وversion وupdate وhelp. وكل ما عدا ذلك يأتي من مستند API.

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

الخيار	المعنى
`-o, --output json\|table\|yaml`	التنسيق. القيمة الافتراضية هي `table` على الطرفية و`json` عند التوجيه (piped).
`--profile`, `--api-url`	تسجيل الدخول المخزن والموقع المحدد.
`-y, --yes`	تخطي التأكيد للأوامر المدفوعة أو التي تترتب عليها إجراءات هامة.
`--idempotency-key <k>`	اختيار مفتاح لأمر مدفوع.
`--retry <n>`	عند استلام رمز HTTP 429، يتم الانتظار لمدة `Retry-After` وإعادة المحاولة حتى n مرات.
`--timeout <s>`	عدد الثواني للانتظار حتى استلام ترويسات الاستجابة (الافتراضي 60).
`--debug`	عرض تبادل بيانات HTTP على مخرج الأخطاء المعياري (stderr) مع إخفاء المفاتيح.

الأوامر التي تقتطع من الرصيد أو تحذف بيانات تطلب تأكيداً، وإذا كانت مدفوعة، فإنها ترسل رمز Idempotency-Key مُنشأ تلقائياً (يتم طباعته على stderr ليتسنى لك إعادة المحاولة بأمان باستخدام --idempotency-key). وفي حال عدم وجود طرفية، يتم رفض التنفيذ ما لم يتم تمرير --yes.

رموز الخروج

الرمز	المعنى
0	نجاح
1	خطأ آخر (شبكة، أو خطأ HTTP 4xx/5xx غير مدرج)
2	خطأ في الاستخدام
3	غير مسموح (401/403)
4	غير موجود (404)
5	تجاوز حد الاستخدام (429)
6	التأكيد مطلوب أو تم رفضه
130	تم المقاطعة

الملفات الشخصية والبيئة

يعرض cmp config الملفات الشخصية، ويقوم cmp config use <name> بالتبديل بينها؛ ويستخدم عملاء الموزع نطاقهم الخاص: cmp login --api-url https://shop.example.net --profile shop. الأولوية: الخيار، البيئة، ملف التكوين. المتغيرات: CMP_TOKEN وCMP_PROFILE وCMP_API_URL وCMP_OUTPUT وCMP_CONFIG_DIR وCMP_ALLOW_HTTP وCMP_UPDATE_URL.

GitHub Actions:

yaml

- name: Install cmp
  run: |
    curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh
    echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
- name: List running VMs
  env:
    CMP_TOKEN: ${{ secrets.CMP_TOKEN }}   # a read-only key
  run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname'

إكمال الأوامر في الصدفة (Shell completion): cmp completion bash|zsh|fish|powershell.

التحديث وإلغاء التثبيت

bash

cmp version
cmp update --check
cmp update

يقوم cmp update بتنزيل latest.json وSHA256SUMS والتوقيع الرقمي، ويتحقق من صحة التوقيع باستخدام المفتاح العام المدمج في الملف الثنائي قيد التشغيل، ثم يتحقق من تجزئة الحزمة (hash) وبعدها فقط يستبدل نفسه. يتطلب التراجع إلى إصدار سابق استخدام --force. عند تحديث NexCMP، تفرِّم اللوحة إصدار CLI الذي يتماشى مع الإصدار الجديد.

لإلغاء التثبيت، احذف الملف الثنائي cmp ومجلد التكوين (يعرضه cmp config path). قم بإلغاء تنشيط المفتاح ضمن API keys في حال ضياع الجهاز.

التحقق

يطبع cmp version الإصدار وإصدار مستند API.
cmp login، ثم الموافقة في المتصفح، وبعدها يعرض cmp whoami الملف الشخصي ورابط لوحتك.
يعرض cmp vm list الأجهزة الافتراضية الخاصة بك؛ ويعرض cmp vm list -o json | jq . بيانات JSON الخام.

الحدود والملاحظات

تعتمد قائمة الأوامر على النسخة المبنية لديك: يتم إنشاء الحزم من مستند OpenAPI الخاص بالتثبيت عند بناء الإصدار، لذا فإن أي منتج معطل في نسختك لن يكون له أمر مقابل. استخدم cmp api للوصول إلى مسار لا يتعرف عليه CLI.
أداة CLI تخضع لرخصة MIT.
كل حزمة موقعة بمفتاح ed25519؛ ومفتاح التوقيع مثبت داخل المثبت والملف الثنائي، ولا يتم جلبه وقت التحديث.
المفاتيح محدودة لكل مفتاح ولكل حساب (راجع REST API).

استكشاف الأخطاء وإصلاحها

العَرَض	السبب	الحل
يعيد `curl .../cli/install.sh` الرمز 404	إصدار الخادم لا يحتوي على مجلد CLI، أو أن المضيف لا يمتلك ترخيصاً صالحاً	تحقق من `https://<domain>/cli/latest.json` والنطاق؛ ثم قم بتحديث NexCMP.
"لم يتم التحقق من صحة التوقيع"	`ssh-keygen` مفقود أو قديم جداً	قم بتثبيت OpenSSH 8.0+، أو اضبط `CMP_REQUIRE_SIGNATURE=0` فقط إذا كنت تقبل المخاطرة.
`cmp login` يشير إلى انتهاء صلاحية الرمز	انقضاء 10 دقائق	قم بتشغيل `cmp login` مرة أخرى.
رمز الخروج 3	المفتاح يفتقر إلى نطاق، أو انتهت صلاحيته، أو تم إلغاؤه	`cmp whoami`؛ أنشئ المفتاح أو أعد اعتماده بنطاقات أكثر.
رمز الخروج 6 في برنامج نصي	أمر مدفوع أو مدمر بدون وحدة طرفية	أضف `--yes` (بالإضافة إلى `--idempotency-key` الخاص بك).
"يرفض إرسال مفتاح عبر http"	رابط API بصيغة http عادي	استخدم `https://`، أو استخدم `CMP_ALLOW_HTTP=1` للمختبر فقط.
المتصفح يفتح الموقع الخطأ	`--api-url` غير معين للموزع	`cmp login --api-url https://<reseller-domain>`.

cmp أداة سطر الأوامر ​

الوظيفة ​

المتطلبات ​

تجهيز البنية التحتية ​

التثبيت (للعميل) ​

تسجيل الدخول ​

استخدام الأوامر ​

رموز الخروج ​

الملفات الشخصية والبيئة ​

التحديث وإلغاء التثبيت ​

التحقق ​

الحدود والملاحظات ​

استكشاف الأخطاء وإصلاحها ​

`cmp` أداة سطر الأوامر

الوظيفة

المتطلبات

تجهيز البنية التحتية

التثبيت (للعميل)

تسجيل الدخول

استخدام الأوامر

رموز الخروج

الملفات الشخصية والبيئة

التحديث وإلغاء التثبيت

التحقق

الحدود والملاحظات

استكشاف الأخطاء وإصلاحها