وضع Cursor CLI Headless: --print و --force وسكربتات تعدّل الملفات

04-non-interactive غطى --no-interactive ليشغّل الـ Agent حتى النهاية دون انتظارك. هذا المنشور يتقدّم: وضع headless مع -p / --print لتشغيلات "المخرجات إلى الطرفية فقط"، plus --force (أو --yolo) حتى يعدّل الـ Agent فعلياً الملفات في مشروعك — مناسب لـ CI، JSDoc دفعة، إصلاح lint تلقائي، وتوليد التقارير.

باختصار: لا نافذة Cursor، لا تأكيدات بأزرار؛ سكربت يستدعي CLI لتغيير الكود، ثم السكربت يكمل.

--print: غير تفاعلي، مخرجات إلى الطرفية

cursor agent -p "What does this project do?"
# or
cursor agent --print "List all API endpoints under src/"

بدون --force: الـ Agent يمكنه قراءة الملفات والبحث في الكود وإرجاع التحليل، لكن لا يكتب إلى الملفات — يقترح فقط أو يطبع المحتوى في المخرجات
جيد لـ: سؤال وجواب، تحليل، كتابة تقارير إلى stdout، piping أو تحليل في السكربتات

إذن -p لوحدها تعني "شغّل حتى النهاية، مخرجات إلى الطرفية"؛ هل يغيّر الملفات يعتمد على إضافة --force.

--force: السماح بتعديل الملفات مباشرة

مع --print و**--force** (أو --yolo)، الـ Agent يستطيع إنشاء وتعديل وحذف ملفات دون سؤال Y/N:

cursor agent -p --force "Refactor src/utils.js to ES6+ syntax"

حالة الاستخدام	مثال
إعادة هيكلة ملف واحد	`agent -p --force "Refactor src/foo.ts to use async/await"`
إصلاح lint حسب الإعداد	`agent -p --force "Fix all auto-fixable errors per .eslintrc"`
JSDoc دفعة	انظر مثال السكربت أدناه
توليد ملف في المشروع	`agent -p --force "Generate CONTRIBUTING.md from README"`

⚠️ قبل استخدام --force في السكربتات، جرّب على ملف واحد أو نطاق صغير أولاً لتأكيد السلوك، ثم وسّع إلى المستودع بالكامل.

مثال سكربت: JSDoc دفعة

#!/bin/bash
# For each .js under src/, ask Agent to add JSDoc and write directly
find src/ -name "*.js" | while read -r file; do
  echo "Processing $file..."
  cursor agent -p --force "Add full JSDoc comments to $file, editing the file in place"
done

كل ملف يُقرأ ويُكتب من الـ Agent، فشغّله على نسخة من المشروع أو فرع، أو جرّب ملفاً أو اثنين أولاً.

مثال سكربت: مراجعة كود تلقائية وكتابة تقرير

#!/bin/bash
cursor agent -p --force --output-format text \
  "Do a code review of recent changes: readability, potential bugs, security, best practices. Write conclusions and concrete suggestions to review.txt"

--output-format text يبقي المخرجات نصاً عادياً للكتابة إلى ملف أو piping إلى grep/سكربتات. المنشور التالي يغطي json وstream-json.

البيئة: مفتاح API

وضع headless غالباً يعمل حيث لا توجد نافذة Cursor (مثلاً CI، آلة بعيدة)، فتحتاج مصادقة:

اضبط المتغير: export CURSOR_API_KEY=your_key
أو شغّل cursor auth login في تلك البيئة أولاً (إن كان مدعوماً)

بدون ذلك ستحصل على أخطاء ولن يعمل الـ Agent.

الفرق عن --no-interactive (باختصار)

الوضع	الاستخدام النموذجي	يعدّل الملفات؟
`--no-interactive`	تشغيل في الطرفية، مشاهدة المخرجات خطوة بخطوة، لا ضغط مفتاح	يمكنه التعديل، لكن قد يسأل (حسب الإعداد)
`-p` / `--print`	سكربتات، CI، غير تفاعلي كلياً، مخرجات إلى stdout	افتراضياً لا
`-p --force`	نفسه، لكن السماح للـ Agent بتعديل الملفات	نعم، بلا سؤال

إذن: لسكربتات "تغيّر الملفات فعلياً" استخدم -p --force؛ للتحليل أو التقارير إلى الطرفية فقط، -p كافٍ.

ملخص

-p / --print: غير تفاعلي، مخرجات إلى الطرفية عند الانتهاء؛ افتراضياً لا تعديل ملفات
--force / --yolo: في وضع print، السماح للـ Agent بتعديل الملفات؛ جيد للسكربتات وCI
في السكربتات/CI، اضبط CURSOR_API_KEY أو أكمِل تسجيل الدخول
جرّب على نطاق صغير قبل التشغيل على المستودع بالكامل

التالي: 11-output-ci — تنسيقات المخرجات text / json / stream-json وأمثلة تكامل CI.