# @azothos/cli

الأمر `azoth`: مرّر استدعاءات أداة برمجة بالذكاء الاصطناعي عبر البوابة، وسمِّ تلك الاستدعاءات في إيداعاتك، وأبلِغ عن الاستخدام، واطلب من الموجِّه نموذجًا، وشغّل مجموعات اختبارات الانحدار في CI.

```
npm install -g @azothos/cli
azoth --help

# or without installing
npx @azothos/cli --help
```

> الحزمة هي `@azothos/cli`، للإصدار 18 من Node.js أو أحدث. لا توجد حزمة `@azoth/cli`، والأمر `npx azoth` ليس Azoth: اسم npm هذا يملكه شخص آخر.

## التهيئة

عيّن `AZOTH_API_KEY` — و`AZOTH_BASE_URL` لنشر مستضاف ذاتيًا — أو اكتبهما بصيغة `apiKey` و`baseUrl` في `~/.azoth/config.json`. ومتغيرات البيئة لها الأولوية.

## azoth proxy

- مُرحِّل على جهازك لأي أداة تقبل عنوان URL أساسيًا لـ OpenAI: وجّهها إلى `http://127.0.0.1:8787/v1`، بأي مفتاح API.
- يذهب كل استدعاء إلى بوابة مساحة عملك بمفتاح مساحة عملك، فيخضع هناك للحوكمة ويُختم؛ ولا يُمرَّر مفتاح الأداة نفسها أبدًا.
- لا يحتفظ المُرحِّل إلا بالمرجع الذي تحمله كل إجابة — إيصالها الموقّع، أو تتبّع الإجابة المتدفقة — في `~/.azoth/receipts.jsonl`، لمدة 7 أيام. ولا يجيب إلا هذا الجهاز.

```
azoth proxy                                      # relay on http://127.0.0.1:8787/v1
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1   # or the tool's own setting; any API key
```

## azoth hook install

- يضيف خطاف git من نوع `commit-msg` إلى المستودع الحالي: يحصل كل إيداع على تذييل `Azoth-Receipt:` واحد لكل استدعاء رآه المُرحِّل منذ الإيداع الأخير، بحد أقصى آخر 5.
- حين يقرأ Azoth المستودع، يُعرض هذا الإيداع على أنه مرتبط بالاستدعاء المختوم: إنه يسمّي استدعاءً ختمته البوابة، وليس أبدًا دليلًا على أن الشيفرة جاءت منه.
- لا يمنع الخطاف أي إيداع أبدًا، ولا يضيف شيئًا إلى رسالة فارغة أو إلى دمج، ولا يستبدل أبدًا خطافًا لم يكتبه — ومع husky أو commitlint، أضف `azoth hook run "$1" || true` إلى خطافك. ويزيله الأمر `azoth hook uninstall`.

```
azoth hook install

git commit -m "Fix the retry on 429"
# → Azoth-Receipt: eyJhbGciOiJFZERTQSIs…   (one trailer per relayed call, the latest 5)
```

## أوامر أخرى

- `azoth ingest [file]` — الإبلاغ عن أحداث الاستخدام من ملف، أو من stdin، أو عبر الخيارات
- `azoth route` — طلب نموذج من الموجِّه (`--mode cost|quality|balanced`)
- `azoth budget` — طباعة كل ميزانية واستخدامها؛ ويجعل الخيار `--exit-on-exceeded` منه بوابة في CI
- `azoth test run <suite.json>` — تشغيل مجموعة اختبارات انحدار عبر البوابة؛ ويخرج بالرمز 1 حين تفشل حالة

## في CI

```
# .github/workflows/ai-regression.yml
- run: npx --yes @azothos/cli test run suite.json
  env:
    AZOTH_API_KEY: ${{ secrets.AZOTH_API_KEY }}
```
