البدء السريع بأداة SAHMK CLI

1. التثبيت

تأتي أداة SAHMK CLI ضمن حزمة Python SDK:

pip install -U sahmk

بعد التثبيت، يصبح الأمر sahmk متاحاً في الطرفية.

إذا لم تظهر الميزات الموثقة حديثاً، فحدّث الحزمة باستخدام pip install -U sahmk.

2. إعداد مفتاح API

احصل على مفتاحك المجاني من sahmk.sa/developers.

الخيار 1: متغير بيئة (موصى به)

export SAHMK_API_KEY="your_api_key_here"

أضف هذا إلى ~/.bashrc أو ~/.zshrc لحفظ الإعداد دائماً.

الخيار 2: تمرير المفتاح مع كل أمر

sahmk quote 2222 --api-key your_api_key_here

3. أول أمر لك

اجلب سعر سهم Aramco باستخدام المعرّف (الرمز في هذا المثال): 2222):

sahmk quote 2222

sahmk quote "أرامكو السعودية"

{
  "symbol": "2222",
  "name_en": "Saudi Arabian Oil Co",
  "price": 25.86,
  "change": 0.18,
  "change_percent": 0.7,
  "volume": 9803705,
  "value": 252308343.0,
  "liquidity": {
    "inflow_value": 184950463.03,
    "outflow_value": 67357881.91,
    "net_value": 117592581.12
  }
}

استخدم --compact لإخراج النتيجة في سطر واحد، وهو مناسب للتمرير:

sahmk quote 2222 --compact

تقبل أوامر الأسعار الرمز أو الاسم العربي أو الإنجليزي أو الاسم البديل. إذا كان الإدخال ملتبساً، فأعد التنفيذ باستخدام الرمز الدقيق.

4. أوامر السوق

ملخص السوق (مؤشر تاسي)

sahmk market summary

أكبر الرابحين والخاسرين

sahmk market gainers --limit 5
sahmk market losers --limit 5

الأسهم الأعلى حجماً وقيمةً

sahmk market volume --limit 10
sahmk market value --limit 10

أداء القطاعات

sahmk market sectors

5. أوامر بيانات الأسهم

أسعار مجموعة أسهم (Starter+)

sahmk quotes 2222,الراجحي,stc

بيانات OHLCV التاريخية (Starter+)

sahmk historical 2222 --from 2026-01-01 --to 2026-01-31 --interval 1d

خيارات الفاصل: 1d (يومي), 1w (أسبوعي), 1m (شهري), 30m, و 60m (تُطبق حدود الباقة والنطاق الزمني).

ملف الشركة (مجاني+)

sahmk company 2222

يعيد المؤشرات الأساسية والفنية والتقييم وبيانات المحللين بحسب الباقة.

القوائم المالية (Starter+)

sahmk financials 2222

يعيد قوائم الدخل والميزانيات والتدفقات النقدية.

سجل توزيعات الأرباح (Starter+)

sahmk dividends 2222

يعيد العائد اللاحق والتوزيعات القادمة وسجل الدفعات.

أحداث السهم (Pro+)

sahmk events --symbol 2222 --limit 10

يعيد ملخصات أحداث مولدة بالذكاء الاصطناعي. احذف --symbol لجلب جميع الأحداث الأخيرة.

6. البث في الوقت الفعلي (Pro+)

تابع تحديثات الأسعار مباشرة عبر WebSocket:

sahmk stream 2222,1120

تُطبع الأسعار كأسطر JSON إلى stdout، وتُرسل حالة الاتصال إلى stderr. اضغط Ctrl+C للإيقاف.

{"symbol":"2222","price":25.86,"change":0.18,"change_percent":0.7,"volume":9803705}
{"symbol":"1120","price":108.6,"change":0.2,"change_percent":0.18,"volume":3250100}

7. نصائح احترافية

• →برمجة الصدفة: مرّر --compact المخرجات إلى jq للتصفية:

sahmk quote "Saudi Aramco" --compact | jq '.price'

• →وضع المراقبة: راقب سهماً بتحديث دوري:

watch -n 30 sahmk quote 2222

• →البرمجة الدفعية: ادمجه مع حلقات الصدفة:

for id in 2222 "الراجحي" "stc"; do sahmk quote "$id" --compact; done

• →مخرجات الأخطاء: تُرسل الأخطاء إلى stderr بصيغة JSON، لذلك لن تتعطل برامجك:

sahmk quote INVALID 2>/dev/null || echo "failed"