---
title: أداة سطر الأوامر cmp
description: تثبيت cmp CLI واستخدامها من لوحتك: تسجيل الدخول عبر المتصفح برمز لمرة واحدة، وأوامر منشأة من API، ومخرجات ورموز خروج، واستخدام CI، وتحديثات موقعة.
url: https://nexcmp.com/ar/docs/developers/cmp-cli/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# `cmp` أداة سطر الأوامر {#cmp-command-line-tool}

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

## الوظيفة {#what-it-does}

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

## المتطلبات {#requirements}

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

## تجهيز البنية التحتية {#prepare-the-infrastructure}

لا شيء. تقوم اللوحة بتقديم هذه الملفات من `/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` | المفتاح العام للإصدار. |

## التثبيت (للعميل) {#install-customer}

أنظمة 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
```

![قسم مرجع الAPI الذي يحتوي على أمر تثبيت cmp لنظامي macOS وLinux](https://nexcmp.com/ar/docs/images/developers/cmp-cli-01-install.webp)

## تسجيل الدخول {#log-in}

```bash
cmp login
```

1. تطبع أداة CLI **رمْزاً** لمرة واحدة ورابطاً (`https://cloud.example.com/link?code=WDJB-MJHT`)، وتفتح المتصفح وتنتظر.
2. في المتصفح، قم بتسجيل الدخول إلى البوابة، وافحص اسم العميل، والجهاز، وعنوان IP والبلد، وحدد الأذونات (النطاقات) واتركه يحدد مدة صلاحية المفتاح (الافتراضي 90 يوماً). الأذونات التي تكلف أموالاً أو تحذف بيانات تبدأ بدون تحديد. انقر فوق موافق.
3. تتلقى أداة 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
```

## استخدام الأوامر {#using-commands}

```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`.

### رموز الخروج {#exit-codes}

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

### الملفات الشخصية والبيئة {#profiles-and-environment}

يعرض `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`.

## التحديث وإلغاء التثبيت {#update-and-uninstall}

```bash
cmp version
cmp update --check
cmp update
```

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

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

## التحقق {#verify}

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

## الحدود والملاحظات {#limits-notes}

- تعتمد قائمة الأوامر على النسخة المبنية لديك: يتم إنشاء الحزم من مستند OpenAPI الخاص بالتثبيت عند بناء الإصدار، لذا فإن أي منتج معطل في نسختك لن يكون له أمر مقابل. استخدم `cmp api` للوصول إلى مسار لا يتعرف عليه CLI.
- أداة CLI تخضع لرخصة MIT.
- كل حزمة موقعة بمفتاح ed25519؛ ومفتاح التوقيع مثبت داخل المثبت والملف الثنائي، ولا يتم جلبه وقت التحديث.
- المفاتيح محدودة لكل مفتاح ولكل حساب (راجع [REST API](https://nexcmp.com/ar/docs/developers/api/#rate-limits)).

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

| العَرَض | السبب | الحل |
|---|---|---|
| يعيد `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>`. |