تشغيل Argorant من CLI وفي خطوط CI

أداة CLI غلاف بلا تبعيات فوق REST API نفسها التي يستخدمها تطبيق الويب وموصِّل MCP. وُجدت للحالات التي يكون فيها بناء القوائم جزءًا من سير عمل متكرر لا مهمة يؤديها شخص في يوم ثلاثاء: تحديث ليلي، أو خطوة CI تُبقي CRM محدّثًا، أو حلقة وكيل تحتاج إلى إجابة قابلة للقراءة آليًا. يأخذك هذا الدليل عبر المسار كاملًا، بما في ذلك الأجزاء التي تنفق المال، والشكل الدقيق لتشغيل لا يمكنه إنفاق أكثر مما قصدت.

القاعدة الوحيدة التي يجب أن تستوعبها أولًا

قبل أي أمر: الأوامر reveal وexport وverify --file لا تطلب التأكيد إلا عندما يكون stdin طرفية ولم تمرر -y ولا --json. أما في CI، أو داخل pipe، أو داخل حلقة وكيل، فلا يوجد أي سؤال، وتنفق هذه الأوامر فورًا.

سؤال التأكيد وسيلة راحة للبشر، وليس شبكة أمان أبدًا. فما يتحكم فعلًا في الإنفاق هو الرقم الذي تمرره إلى -n، فاقرأه قبل التشغيل، خاصة في سكربت لن يراقبه أحد.

التثبيت والتشغيل الأول

لا حاجة إلى أي تثبيت إن لم ترغب في ذلك:

npx argorant count "fintech CFOs in germany"

أو ثبّتها على مستوى النظام، واسم الحزمة argorant:

npm install -g argorant

التعامل مع المفاتيح، وأي بيانات اعتماد لها الأولوية

تأخذ أداة CLI مفتاحًا يبدأ بـ ag_live_، تنشئه من الملف الشخصي، مفاتيح API. وهناك ثلاث طرق لتمريره، وترتيب أولوية صارم.

تفاعليًا، على جهازك الخاص

npx argorant login

يطلب الأمر المفتاح مع إخفاء ما تكتبه، ويتحقق منه عبر نقطة نهاية الحساب، ثم يحفظه. والمفتاح المرفوض يفشل فورًا برسالة واضحة، بدلًا من أن يُحفظ ثم يفشل لاحقًا في أمر يكلّف مالًا. ويمكنك أيضًا تمريره مباشرة بالصيغة argorant login <key>.

متغير البيئة، لـ CI والوكلاء

export ARGORANT_API_KEY=ag_live_...

هذه هي الطريقة الصحيحة للسكربتات ومسارات العمل الآلية والوكلاء. لا يُكتب أي شيء على القرص، ويُقرأ المتغير في كل استدعاء.

الأولوية

1. المتغير ARGORANT_API_KEY في البيئة له الأولوية على كل شيء.
2. وإلا يُستخدم المفتاح الذي حفظه argorant login في ~/.argorant/config.json، والمكتوب بالصلاحيات 0600.
3. وفي غياب الاثنين، تنتهي الأوامر برمز الخروج 2 وتطلب منك تسجيل الدخول.

الأمر argorant logout يحذف ملف الإعداد. وإذا كان ARGORANT_API_KEY لا يزال مضبوطًا، تحذّرك الأداة، لأن هذا المتغير له الأولوية وسيبقيك مصادقًا. فاحذفه أيضًا.

نظافة المفاتيح في مسارات العمل الآلية

• مفتاح واحد لكل مسار عمل أو وكيل. فيبقى الاستخدام قابلًا للنسب، وإلغاء مفتاح لا يعطّل غيره أبدًا.
• مكان المفاتيح هو مخزن الأسرار في CI، لا ملفًا مُدرجًا في المستودع، ولا لصقًا في محادثة مشتركة. فسجلات المحادثات تُصدّر وتُصوّر، وإذا حدث ذلك فدوّر المفتاح الآن.
• التدوير دون توقف: أنشئ المفتاح الجديد، وانشره، وتأكد منه بـ npx argorant whoami، ثم ألغِ القديم. يسري الإلغاء فورًا، ويفشل الطلب التالي الذي يستخدمه بالرمز 401.

الأوامر المجانية التي يجب أن تستخدمها بلا تردد

الأمر count يُعيد حجم الشريحة. وsearch يُعيد الأشخاص المطابقين مع إخفاء هويتهم. وcompany يجيب عما إذا كان يمكن الوصول إلى حساب محدد أصلًا. ولا يخصم أي منها أرصدة جهات الاتصال، لكن صلاحيات الحساب والحصص وحدود المعدل تنطبق.

npx argorant count "fintech CFOs in germany"
npx argorant count --keywords logistics --country "United States" --seniority vp
npx argorant search "heads of procurement" --country Germany -n 10

أضف --json إلى أي أمر للحصول على مخرجات قابلة للقراءة آليًا. ويجب أن تستخدمه السكربتات والوكلاء دائمًا: أسماء الحقول ثابتة، أما التنسيق الموجه للبشر فلا، وتحليل المخرجات المنسقة هو الطريقة التي يتعطل بها مسار العمل بصمت عند الترقية.

الفلاتر مشتركة بين كل الأوامر ذات الطابع البحثي، فما تتعلمه مع count ينطبق كما هو على search وreveal وexport وlist create:

--keywords --title --exclude-title --seniority --department --industry
--country --geography --state --city --company --domain
--has-phone --has-linkedin --has-email --verified-only
-n/--limit  -o/--output  --json  -y/--yes  --base  --grade

المعامل --keywords هو المدخل الأوسع والأكثر موثوقية، والفاصلة فيه تعني "أو"، وهو يتفوق عمومًا على --industry. أما --country و--geography فهما الفلتر نفسه، ويقبلان مناطق مثل Europe و EMEA و DACH و Nordics و APAC و LATAM و GCC.

معاملان يتصرفان بشكل مختلف عما يوحي به اسماهما، والأداة تخبرك بذلك بدلًا من التظاهر. المعامل --exclude-title يُطبَّق بالكامل في export وlist create، لكن ليس بعد في count وsearch وreveal، حيث تُكتب ملاحظة إلى stderr. والمعامل --grade يختار بين المجموعة الصارمة القابلة للتسليم والمجموعة الأوسع التي تشمل Catch-all، وهو موصول من البداية إلى النهاية في reveal وexport، لكن المنصة لا تضيّق النتائج بناءً عليه بعد، لذا تحذّرك الأداة بدلًا من الادعاء بأنها فعلت.

هناك ضابطان دائمان في تحليل المعاملات: القيمة غير الرقمية لـ -n توقف التنفيذ بدلًا من الرجوع إلى الحد الافتراضي، والمعامل الذي يتطلب قيمة ويليه معامل آخر يوقف التنفيذ بدلًا من ابتلاعه. وكلاهما موجود لأن المعامل المبتلع قد يرسل طلبًا لم تطلبه أبدًا، وبمالك أنت.

القوائم المحفوظة من الطرفية

القائمة المحفوظة مجموعة فلاتر قابلة لإعادة الاستخدام، لا لقطة مجمدة. وإنشاؤها مجاني ولا يكشف أي شيء.

npx argorant list create --name "DACH CFOs 200+" --title CFO --country DACH
npx argorant list status 42

القوائم مشتركة بين كل الواجهات. فالقائمة التي ينشئها مسار عملك الآلي تظهر في تطبيق الويب، والقائمة التي يبنيها زميلك في التطبيق يراها مسار عملك. ولأن list status مجاني، يستطيع أي مهمة مجدولة مراقبة حركة السوق يوميًا دون إنفاق أي شيء، وهذه أرخص مراقبة يمكنك بناؤها.

عمليات التصدير، ومسار الاسترداد

npx argorant export "fintech CFOs" --country Germany -n 1000 -o leads.csv

ما يحدث، بالترتيب:

1. يتم التحقق من قابلية الكتابة في مسار المخرجات قبل إنشاء المهمة، فلا يمكن أن يكلّفك مسار خاطئ ثمن ملف لا تستطيع حفظه.
2. يُطلب منك التأكيد، ما لم تمرر -y أو --json أو لم يكن stdin طرفية.
3. تُنشأ المهمة ويُستعلم عنها دوريًا. ويجري التحقق في هذه اللحظة، ولا تُحتسب إلا الصفوف القابلة للتسليم.
4. يصل ملف CSV إلى المسار المحدد في -o، ويُطبع عدد الصفوف.

قيمتان افتراضيتان يجدر معرفتهما: has_email قيمته الافتراضية true لتحمل الصفوف المصدّرة عنوانًا، وجهات الاتصال التي صدّرتها سابقًا يتم تخطيها ما لم تمرر --include-exported. والثانية هي ما يجعل التحديث المجدول يُعيد أشخاصًا جددًا بدلًا من إعادة تسجيل الجميع.

تفرع: توقفت العملية في منتصف التصدير

التصدير المدفوع لا يضيع أبدًا. فإذا توقفت الأداة بعد إنشاء المهمة، فإنها تطبع أوامر الاسترداد الدقيقة، وكلاهما مجاني:

npx argorant export status 12345
npx argorant export download 12345 -o leads.csv

تفرع: التصدير يتجاوز 50,000 صف

فوق 50,000 صف تصبح المهمة دفعة من عدة أجزاء. تستعلم الأداة عن الدفعة وتكتب ملفًا لكل جزء: leads-part1.csv وleads-part2.csv وهكذا، مع طباعة معرّف الدفعة لتتمكن من جلبها مجددًا لاحقًا:

npx argorant export status 987 --batch
npx argorant export download 987 --batch -o leads.csv

التحقق من عناوينك الخاصة

الأمر verify يفحص العناوين التي تجلبها بنفسك، ويكلّف نصف رصيد لكل فحص من رصيدك المعتاد.

npx argorant verify someone@company.com
npx argorant verify --file emails.csv -o out.csv
npx argorant verify --file contacts.csv --column work_email -o out.csv

مع ملف، يستخرج العناوين ويزيل المكرر منها، ويرسلها على دفعات من 500، ويكتب ملف CSV بالأعمدة email,status,deliverable، واسمه الافتراضي argorant-verified.csv. ويوضح الملخص عدد العناوين القابلة للتسليم، وعدد الفحوصات المحتسبة، وعدد ما كان مجانيًا لوجود نتيجة حديثة مسبقًا. وإذا لم يُعثر على أي عنوان، يتوقف ويقترح --column بدلًا من ألا يفعل شيئًا بصمت.

جهات الاتصال المصدّرة من Argorant يتم التحقق منها بالفعل وقت التصدير، لذا فهذا الأمر مخصص للقوائم القادمة من مصادر أخرى.

رموز الخروج: العقد بينك وبين مسار العمل

تفرّع بناءً على رموز الخروج، لا على نصوص الأخطاء أبدًا.

• 0 نجاح.
• 1 خطأ عام: استخدام خاطئ، أو عطل في الشبكة، أو مهمة فشلت على الخادم. شيء ما معطّل فعلًا.
• 2 غير مصادق. لا يوجد مفتاح، أو رُفض المفتاح. أصلح بيانات الاعتماد ثم أعد المحاولة.
• 3 ممنوع. المفتاح صالح لكنه يفتقر إلى الصلاحية. وتوسيع صلاحيات المفتاح قرار بشري، لا إعادة محاولة.
• 4 حد المعدل أو الحصة اليومية. توقف قليلًا واستأنف لاحقًا.
• 5 يتطلب دفعًا أو ترقية الخطة. والرسالة تتضمن الرابط.

الرمز 5 منفصل عمدًا عن 1 لهذا السبب تحديدًا. فمسار العمل الذي يعيد محاولة مشكلة دفع في حلقة هو مسار يوقظك في الرابعة فجرًا بسبب شيء لا يحله إلا إنسان معه بطاقة ائتمان.

نمط shell يصمد في الواقع:

npx argorant export --keywords fintech --country Germany -n 500 -o leads.csv --yes
case $? in
  0) echo "done" ;;
  2|3) echo "credential problem, stopping"; exit 1 ;;
  4) echo "rate limited, retry later" ;;
  5) echo "needs credits, notify a human" ;;
  *) echo "failed"; exit 1 ;;
esac

تقابل هذه الرموز مباشرة رموز حالة HTTP في REST API: يصبح 401 هو 2، و403 هو 3، و429 هو 4، و402 هو 5. فالوكيل الذي يستخدم الواجهتين يمكنه مشاركة مسار واحد لمعالجة الأخطاء.

مهمة cron تحدّث شريحة

الشكل الذي ينجح في بيئة الإنتاج يضع كل خطوة مجانية قبل كل خطوة مدفوعة، فلا تكلّف الليلة السيئة شيئًا.

#!/usr/bin/env bash
set -euo pipefail
export ARGORANT_API_KEY="$ARGORANT_KEY_FROM_SECRET_STORE"
LIMIT=500
OUT="/var/data/leads-$(date +%F).csv"
FILTERS="--keywords fintech --title CFO --country Germany"

# 1. Free: how big is the segment right now?
SIZE=$(npx argorant count $FILTERS --json | jq -r '.count')
if [ "$SIZE" -lt 200 ]; then
  echo "segment too small to bother, skipping"; exit 0
fi

# 2. Paid: export, with an explicit ceiling and no prompt.
npx argorant export $FILTERS -n "$LIMIT" -o "$OUT" --yes --json
case $? in
  0) ./push-to-sequencer.sh "$OUT" ;;
  4) echo "rate limited, will run tomorrow" ; exit 0 ;;
  5) ./notify-human.sh "Argorant needs credits" ; exit 0 ;;
  *) exit 1 ;;
esac

0 6 * * 1 /opt/jobs/argorant-refresh.sh >> /var/log/argorant.log 2>&1

أربع خصائص تجعل هذا السكربت آمنًا لا مجرد عامل. حد الصفوف متغير مسمّى في الأعلى، لا قيمة افتراضية مدفونة داخل أمر. وفحص الحالة المجاني يجري قبل احتساب أي شيء. ومشكلة الدفع تُبلغ شخصًا بدلًا من إعادة المحاولة. وحد المعدل يُنهي التنفيذ بالرمز صفر، لأن تشغيل الغد سيلتقطه، ولأن فشل البناء بسبب حد مؤقت يعوّد الناس على تجاهل حالات الفشل.

أخطاء ستقع فيها مرة واحدة بالضبط

• افتراض أن سؤال التأكيد سينقذك. في CI لا يوجد سؤال. قيمة -n هي الميزانية.
• تحليل المخرجات الموجهة للبشر. استخدم --json في كل أتمتة، منذ أول commit.
• ترك ARGORANT_API_KEY مضبوطًا بعد تسجيل الخروج. البيئة لها الأولوية، فتبقى مصادقًا.
• إعادة محاولة الرمز 5. لا عدد من المحاولات يُنتج أرصدة.
• إعادة تشغيل تصدير فاشل من البداية. إذا أُنشئت المهمة فقد احتُسبت، والأمر export download يجلبها مجانًا. تحقق قبل إعادة التشغيل.
• مشاركة مفتاح واحد بين ثلاثة مسارات عمل. إذا ألغيته مرة واحدة عطّلت الثلاثة، ولن تعرف أبدًا أيها سرّبه.

ملاحظة أخيرة عن النطاق: الأمر argorant campaigns موجود لكنه واجهة تشغيل داخلية، ومفتاح العميل العادي يحصل فيه على 401 أو 403. وهذا يعني أن النظام يعمل بشكل صحيح، لا خطأ يجب الإبلاغ عنه. أما الأوامر المهمة للعملاء فهي count وlist وexport وverify، إضافة إلى أي تكامل يرسل الملف النهائي إلى أداة التسلسل لديك.