مساحة عمل واجهة برمجة التطبيقات (API) الخاصة بك تعيش في واجهة مستخدم رسومية (GUI). يوم عملك يعيش في الطرفية (terminal). كل تبديل سياق بين الاثنين يكلف ثوانيًا وتركيزًا، وفي مسار تكامل مستمر (CI) أو جلسة عامل ذكاء اصطناعي (AI agent)، لا تكون الواجهة الرسومية خيارًا حتى. يأتي Apidog CLI ليسد هذه الفجوة: فهو يجلب منصة Apidog بأكملها، والاختبارات، ونقاط النهاية، والمخططات، والبيئات، وتوقعات المحاكاة، والوثائق، إلى موجه الأوامر الذي لديك بالفعل مفتوحًا.
تعريف صادق واحد قبل أي شيء آخر. Apidog CLI ليس مجرد أداة `curl` أخرى. إذا كنت ترغب في إطلاق طلب GET لمرة واحدة وتفحص JSON، فإن `curl` و`HTTPie` يقومان بذلك بشكل جيد بالفعل، ويغطي ملخص عملاء REST للطرفية وTUI الجانب التفاعلي. Apidog CLI هو عميل لمساحة عمل واجهة برمجة التطبيقات الخاصة بك نفسها: يقوم بتشغيل سيناريوهات الاختبار التي قمت ببنائها، ويقرأ ويحدّث عقد واجهة برمجة التطبيقات، وينقل المواصفات داخل وخارج المشروع، كل ذلك من الأوامر التي يمكن أن يستدعيها برنامج نصي أو عامل.
ماذا يعني "يعيش في الطرفية الخاصة بك" هنا
أدوات HTTP الطرفية تتعامل مع طلب واحد في كل مرة. يعمل Apidog CLI على مستوى المشروع. يمتد سطح أوامره إلى أكثر من أربعين مجموعة، وتتجمع في خمس وظائف:
| الوظيفة | الأوامر |
|---|---|
| تشغيل الاختبارات | run, test-scenario, test-suite, test-case, test-data, test-report |
| إدارة العقد | endpoint, schema, folder, common-parameter, response-component, security-scheme |
| شحن الوثائق والمحاكاة | doc, docs-site, shared-doc, mock |
| التهيئة والاتصال | environment, variables, vault, database-connection, websocket, socketio |
| العمل كفريق | branch, merge-request, runner, scheduled-task, audit-log, import, export |
يدعم كل أمر ` --help`، والإخراج هو JSON منظم، وتتضمن معظم الردود `agentHints.nextSteps` تخبرك (أو عامل الذكاء الاصطناعي الخاص بك) بما يجب تشغيله بعد ذلك. قد تبدو هذه التفاصيل الأخيرة صغيرة. لكنها تغير إحساس الأداة: يوجه CLI سير العمل بدلاً من افتراض أنك حفظته.
ثبته بأمر واحد
يتم شحن CLI كحزمة npm (apidog-cli) ويعمل على macOS و Linux و Windows. يتطلب Node.js الإصدار 16 أو أحدث.
npm install -g apidog-cli
apidog --version
ثم قم بتسجيل الدخول باستخدام رمز وصول API. احصل عليه من تطبيق Apidog: انقر على صورتك الرمزية، وافتح إعدادات الحساب، وانسخ الرمز تحت "API Access Token".
apidog login --with-token <YOUR_TOKEN>
يتم حفظ الرمز في `~/.apidog/config.toml`، لذا ابقه بعيدًا عن مستودعاتك وسجلاتك؛ في CI، مرره في كل تشغيل باستخدام ` --access-token` من سر بدلاً من ذلك. تغطي أربع علامات عامة معظم السياقات: ` --project` يختار المشروع، ` --branch` يختار الفرع، ` --access-token` يتجاوز تسجيل الدخول المحفوظ، و` --api-base-url` يوجه CLI إلى نشر Apidog مستضاف ذاتيًا. يشرح دليل مصادقة Apidog CLI الرموز المميزة لـ CI بالتفصيل.
شغّل الاختبارات التي أنشأتها بصريًا
إليك سير العمل الذي صُمم حوله CLI. تقوم بإنشاء سيناريو اختبار في محرر Apidog المرئي: طلبات متسلسلة، متغيرات مستخرجة من استجابة واحدة ومحقونة في التالية، تأكيدات على الحالة والنص. ثم تقوم بتشغيله في أي مكان توجد فيه صدفة.
# انسخ هذا الأمر، بما في ذلك المعرفات، من علامة تبويب CI/CD للسيناريو
apidog run -t <scenario_id> -e <env_id> -r cli
يخرج الأمر `0` عندما تمر جميع التأكيدات ويكون غير صفري عندما يفشل أي شيء، لذا فإن المسار يعتمد عليه بدون أي إضافات. قم بتبديل `-e` لتوجيه نفس السيناريو إلى بيئات التطوير أو الاختبار أو الإنتاج. قم بتغذيته بملف CSV أو JSON وسيقوم بتكرار السيناريو على كل صف، وهي طريقة عمل الاختبار الموجه بالبيانات دون تكرار الخطوات. إذا كنت تبدأ من الصفر، فإن التجول خطوة بخطوة في REST API ينتقل من التثبيت إلى أول تشغيل ناجح.
تخرج التقارير بأربعة تنسيقات: `cli` يطبع النتائج خطوة بخطوة إلى الطرفية، بينما `html` و`json` و`junit` يتم حفظها في `apidog-reports/` للوحات المعلومات وتحف CI. ادمجها بحرية، كما في ` -r cli,junit`. يوضح دليل تقارير الاختبار كيف يبدو كل تنسيق.
بالنسبة للتشغيلات التي لا ينبغي أن تعتمد على جهاز الكمبيوتر المحمول الخاص بك، تدير أوامر `runner` و`scheduled-task` المشغلات المستضافة ذاتيًا والتنفيذات المجدولة، وهي نفس الآلية الكامنة وراء اختبارات API المجدولة في Apidog.
إدارة عقد واجهة برمجة التطبيقات دون فتح التطبيق
هذا هو الجزء الذي لا تحمله أي أداة اختبار طرفية أخرى. يمكن لنفس CLI الذي يقوم بتشغيل اختباراتك قراءة وكتابة تعريف واجهة برمجة التطبيقات نفسها:
apidog endpoint list --project <project_id>
apidog schema get <schema_id>
apidog environment list
apidog mock list
نقاط النهاية، ومخططات البيانات، والمجلدات، والبيئات، والمتغيرات، ومخططات الأمان، والمكونات القابلة لإعادة الاستخدام، كلها قابلة للاستعلام والتعديل. يدير أمر `mock` توقعات المحاكاة، وهي أزواج الطلب والاستجابة الثابتة التي يعيدها خادمك الوهمي. تتفاعل أوامر `doc` و`docs-site` مع الوثائق المنشورة. تحتوي نقاط نهاية WebSocket وSocket.IO على مجموعاتها الخاصة، ويغطي `database-connection` تكوينات قاعدة البيانات التي تقرأها سيناريوهات الاختبار الخاصة بك.
يتحدث الاستيراد والتصدير التنسيقات المهمة: OpenAPI 3.x و Swagger 2.0 (الـ مواصفات التي تتوحد عليها معظم سلاسل الأدوات)، بالإضافة إلى مجموعات Postman. وهذا يجعل CLI جسرًا في نصوص الترحيل: اسحب مواصفة من نظام واحد، وادفعها إلى Apidog، وقم بإصدار التبادل بأكمله.
apidog import openapi.json --project <project_id>
apidog export --format openapi
مصمم بحيث يمكن لعوامل الذكاء الاصطناعي قيادته
تعتمد إصدارات عام 2026 من CLI بقوة على فكرة واحدة: يجب أن يكون عامل الذكاء الاصطناعي البرمجي قادرًا على تشغيل مساحة عمل واجهة برمجة التطبيقات الخاصة بك بأمان كما يفعل الإنسان. أربع قطع تجعل ذلك ممكنًا.
أولاً، الإخراج المنظم. يعيد كل أمر JSON يمكن لعامل الذكاء الاصطناعي تحليله، وتخبره `agentHints.nextSteps` بما يجب فعله بعد كل نتيجة، بما في ذلك كيفية التعافي من الأخطاء.
ثانياً، مخطط الإدخال المنشور. تعرض `apidog cli-schema list` و`apidog cli-schema get` الشكل الدقيق لـ JSON الذي يتوقعه كل أمر كتابة، وتتحقق `apidog cli-schema validate` من الحمولة قبل أن يلمس أي شيء المشروع. طقوس الكتابة الآمنة هي نفسها دائمًا: احصل على المخطط، أنشئ JSON، قم بالتحقق منه، وفقط بعد ذلك قم بتشغيل `create` أو `update`.
ثالثاً، مهارة مجمعة. يشحن أمر `skill` معرفة تشغيل CLI في شكل يمكن للعوامل تحميله مباشرةً، وهذا هو السبب وراء سبب بناء مهارة Apidog CLI. في قياساتنا الخاصة، استخدمت العوامل التي تعمل من خلال مخطط CLI حوالي 30% أقل من استدعاءات الأدوات و 25% أقل من الرموز المميزة مقارنة بالعوامل التي تخمن الحمولات؛ يتم تفصيل الأرقام في هذا التحليل.
رابعًا، بوابات الأذونات. بشكل افتراضي، يتم حظر عمليات الكتابة إلى فرع مصدرها الذكاء الاصطناعي حتى يقوم إنسان بتمكين "External AI Edit Permissions" (في عميل Apidog 2.8.32 أو أحدث، ضمن إعدادات المشروع، إعدادات الميزات، إعدادات ميزات الذكاء الاصطناعي). البديل هو فرع AI: فرع معزول حيث يقوم عامل الذكاء الاصطناعي باستيراد الموارد التي يحتاجها، ويقوم بتعديلاته، ويعيد النتيجة كطلب دمج للمراجعة. الأفرع التي لم يتم لمسها بواسطة الذكاء الاصطناعي تُؤرشف تلقائيًا بعد 24 ساعة، لذلك لا تتراكم التجارب. يبقى عقد واجهة برمجة التطبيقات الخاص بك قابلاً للمراجعة حتى عندما يكتب عامل الذكاء الاصطناعي المسودة الأولى.
ما لا يمثله Apidog CLI
ثلاثة قيود، مصرح بها بوضوح، لأن اختيار الأدوات بناءً على معلومات صادقة أفضل من اكتشاف الثغرات لاحقًا.
إنه ليس عميل طلب تفاعلي. لا يوجد أمر يقوم بكتابة طلب POST مخصص وتنسيق الاستجابة بشكل جميل؛ `curl` و`HTTPie` وعملاء TUI يمتلكون هذه المهمة، وهم أفضل فيها.
إنه ليس مفتوح المصدر. الحزمة مملوكة، وnpm هي قناة التثبيت الوحيدة، والقيام بأي شيء يتجاوز ` --help` يتطلب حساب Apidog. تغطي الطبقة المجانية سير العمل الكامل الموضح هنا، ولكن إذا كان الترخيص القابل للتدقيق مطلبًا صارمًا، فإن المشغل مفتوح المصدر هو التوصية الصادقة.
إنه ليس مستقلاً. CLI هو الذراع الطرفية للمنصة: تعيش السيناريوهات ونقاط النهاية والبيئات في مشروع Apidog الخاص بك، وليس في الملفات المحلية. هذا هو المقايضة التي تمنحك مصدرًا واحدًا للحقيقة عبر التصميم والاختبار والمحاكاة والوثائق.
أين يتناسب في صندوق أدوات الطرفية
مقارنة بالمشغلات الأخرى، يكمن الاختلاف في مكان التأليف. يقوم Newman و Postman CLI بتشغيل مجموعات تم تأليفها في Postman؛ وتقوم Hurl و Bruno بتشغيل اختبارات تم تأليفها كملفات نصية؛ بينما يقوم Apidog CLI بتشغيل سيناريوهات تم تأليفها في محرر مرئي يحتوي أيضًا على عقدك، ومحاكياتك، ووثائقك. يقدم مقارنة Apidog CLI مقابل Newman تعمقًا أكبر، ويتم تصنيف المجال الكامل في أفضل أدوات اختبار API المستندة إلى الطرفية.
إعداد عمل لمعظم الفرق: حافظ على `curl` أو `xh` في الذاكرة العضلية للتحقق السريع، ودع `apidog run` يحمل المجموعات في CI. يتضمن دليل GitHub Actions التفصيلي مسار عمل يمكن نسخه ولصقه للبدء منه.
الأسئلة الشائعة
هل Apidog CLI مجاني للاستخدام؟ نعم. يتم تثبيت الحزمة مجانًا من npm، وتغطي الطبقة المجانية من Apidog بناء السيناريوهات وتشغيلها عبر CLI. تضيف الخطط المدفوعة ميزات على مستوى الفريق، وليس الوصول الأساسي إلى CLI.
هل يحل محل `curl` أو `HTTPie`؟ لا، ولا يحاول ذلك. تلك الأدوات ترسل طلبات مخصصة؛ Apidog CLI يقوم بتشغيل سيناريوهات اختبار محفوظة ويدير موارد المشروع. ينتهي المطاف بمعظم الأطراف بوجود كليهما.
هل يمكن تشغيله بشكل كامل بدون واجهة رسومية في CI؟ نعم. قم بالمصادقة باستخدام ` --access-token` من سر CI، ثم قم بتشغيل `apidog run` باستخدام معرف السيناريو الخاص بك، واجعل بناء النظام يتوقف على رمز الخروج. لا يلزم وجود تطبيق سطح مكتب على المشغل.
ما هي التنسيقات التي يمكن استيرادها وتصديرها؟ OpenAPI 3.x، Swagger 2.0، ومجموعات Postman، في كلا الاتجاهين. وهذا يغطي عمليات الترحيل والدمج.
كيف تستخدمه عوامل الذكاء الاصطناعي بأمان؟ من خلال طقوس المخطط-التحقق-الكتابة وبوابات الأذونات: `cli-schema validate` تكتشف الحمولات المشوهة قبل وصولها، وتحافظ فروع الذكاء الاصطناعي على تعديلات العميل معزولة حتى يقوم إنسان بدمجها. انظر كيف يعمل داخل عامل ذكاء اصطناعي في كيفية استخدام Apidog CLI في Claude Code.
الطرفية هي المكان الذي يتم فيه تشغيل اختباراتك بالفعل وحيث يعمل وكلاء الذكاء الاصطناعي الخاصون بك بالفعل. وضع عميل واجهة برمجة التطبيقات هناك أيضًا يزيل آخر تبديل سياق. قم بتنزيل Apidog، وقم بتثبيت CLI من npm، وقم بتشغيل سيناريو واحد من البداية إلى النهاية؛ تحتوي صفحة Apidog CLI على المرجع الكامل للأوامر عندما تكون مستعدًا لتجاوز `run`.