مرجع واجهة سطر الأوامر (CLI)

مساحة أوامر kazma وkazma-tui وkazma-web الكاملة، كل علم، وأمثلة عاملة — كلها موثّقة مقابل مصدر kazma-cli/.

1. نقاط الدخول

مُعرَّفة في pyproject.toml:73-76:

الأمر	الوحدة	ماهيته
`kazma`	`kazma_cli.main:main`	واجهة سطر الأوامر (CLI) الأساسية (hub، gateway، swarm، project، docs، completion، update).
`kazma-tui`	`kazma_tui.app:main`	لوحة التحكم بواجهة Textual الطرفية (TUI).
`kazma-web`	`kazma_ui.app:main`	خادم واجهة الويب FastAPI (اسم مستعار لـ `kazma serve`).

ملاحظة عن الإطار: الأمر kazma ذو المستوى الأعلى يستخدم تحليلاً يدويًا للمُعاملات argv (سلسلة if/elif فوق sys.argv[1:] في main.py:39-94) — وليس Click. الشجرة الفرعية kazma hub وحدها تستخدم Click (kazma_core/hub/cli.py:104). العلم المبكّر العام --no-banner يُنتزع قبل الإرسال (main.py:28-32).

2. `kazma` — الشجرة ذات المستوى الأعلى

kazma
├── (no args)              # banner + status + help hint
├── status                 # probe running server, print versions
├── serve [port]           # launch Web UI (uvicorn)
├── wizard                 # interactive skill-install wizard
├── hub ...                # skill hub (Click group)
├── docs <build|serve>     # build/serve the Docusaurus docs site
├── completion ...         # shell tab-completion
├── project ...            # .kazma/ project config
├── gateway ...            # gateway control via REST
├── swarm ...              # swarm orchestration via REST
├── update                 # check/install CLI updates
└── --help | -h | help     # print command list

2.1 `kazma` (بلا وسائط)

يطبع لافتة بدء التشغيل، ويُجري فحوصات الإعداد، ويطبع الحالة، وتلميحًا للمساعدة (main.py:35-37). يلتزم بـ --no-banner.

2.2 `kazma status`

يفحص /api/gateway/status و/api/swarm/status على الخادم قيد التشغيل، ويطبع إصدارات Python/Kazma، ومسار الإعداد، وإصدارات الحزم الرئيسية (main.py:352-439).

kazma status

2.3 `kazma serve [port]`

يُطلق واجهة الويب عبر uvicorn kazma_ui.app:create_app --factory. المنفذ الافتراضي 8000. يربط 127.0.0.1 عادةً؛ ويتحوّل إلى 0.0.0.0 فقط عند ضبط KAZMA_SECRET (main.py:97-114, 110).

kazma serve            # 127.0.0.1:8000
kazma serve 8090       # 127.0.0.1:8090
KAZMA_SECRET=xxx kazma serve   # 0.0.0.0:8000 (approval endpoints protected)

الأمان: لا تُشغّل أبدًا kazma serve على 0.0.0.0 بدون KAZMA_SECRET. وإلا فستكون نقطة نهاية الموافقة البشرية في الحلقة (HITL) غير مُوثَّقة.

2.4 `kazma wizard`

يُشغّل معالج تثبيت المهارات التفاعلي (kazma_core.cli.wizard.SkillInstallationWizard، main.py:117-123).

2.5 `kazma docs`

يبني موقع توثيق Docusaurus أو يقدّمه ضمن docs/ (main.py:133-202).

kazma docs build        # npm install && npm run build
kazma docs serve        # npm run start (default port 3000)
kazma docs serve 4000   # custom port

3. `kazma completion`

توليد وتثبيت الإكمال التلقائي للغلاف (tab-completion) (main.py:224-286، completions.py).

الأمر الفرعي	الوصف
`kazma completion bash`	طباعة سكربت إكمال bash.
`kazma completion zsh`	طباعة سكربت إكمال zsh.
`kazma completion powershell` (أسماء مستعارة `pwsh`، `ps`)	طباعة سكربت PowerShell `Register-ArgumentCompleter`.
`kazma completion install [shell]`	كشف الغلاف تلقائيًا (PowerShell على win32؛ zsh/bash على POSIX) وتثبيته.
`--list-models`	طباعة أسماء النماذج المتاحة.
`--list-providers`	طباعة أسماء المُزوّدين.

الأعلام العامة (لبيانات الإكمال): --model، --provider، --yolo، --verbose، --no-banner، --help، -h.

4. `kazma project`

إعداد لكل مشروع عبر .kazma/ (main.py:289-328، project.py).

الأمر الفرعي	الوسائط	الوصف
`kazma project init [path]`	افتراضي `.`	إنشاء `.kazma/` يحوي `rules.yaml` و`context.md` و`personality.yaml` و`tools.yaml` و`history/`. مُساوي (Idempotent).
`kazma project show [path]`	افتراضي `.`	عرض إعداد المشروع المُحلَّل.
`kazma project validate [path]`	افتراضي `.`	التحقق من وجود الملفات المطلوبة، وتحليل YAML، واحتواء `rules.yaml` على `language` و`git_branch`.

5. `kazma gateway`

التحكم بالبوابة متعددة القنوات عبر REST. تقبل جميع الأوامر الفرعية --port N وتتحدث مع http://localhost:{port} (gateway.py).

5.0 العلم `--port` (swarm / gateway)

تستهدف أوامر swarm وgateway الخادم على http://localhost:8000 افتراضيًا. يُحَلّ المنفذ وفق هذه الأولوية:

المصدر	الأولوية
`--port N` (لكل أمر)	الأعلى
`KAZMA_PORT` متغير البيئة	الوسط
`8000` (الافتراضي)	الأدنى

إذا كان الخادم غير قابل للوصول، تطبع واجهة سطر الأوامر (CLI) Server not running. Start with: kazma serve وتخرج برمز 1 (راجع رموز الخروج).

الأمر الفرعي	نقطة النهاية	الوصف
`kazma gateway status`	`GET /api/gateway/status`	جدول المُحوّلات.
`kazma gateway start`	`POST /api/gateway/start`	بدء البوابة.
`kazma gateway stop`	`POST /api/gateway/stop`	إيقاف البوابة.
`kazma gateway restart`	إيقاف + 0.5 ث + بدء	إعادة تشغيل البوابة.
`kazma gateway refresh`	`POST /api/gateway/refresh-adapters`	إعادة مسح المُحوّلات.

kazma gateway status
kazma gateway restart --port 8090

6. `kazma swarm`

تنسيق السرب عبر REST (swarm.py). أعلام القيمة: --model، --provider، --type، --role، --context، --workers، --aggregation، --page، --page-size، --status، --port، --worker. منطقية: --reset.

6.1 الحالة والعمّال

الأمر الفرعي	الوصف
`kazma swarm status`	`GET /api/swarm/status`.
`kazma swarm workers`	سرد العمّال.
`kazma swarm worker add <name> [--model --provider --type --role]`	`POST /api/swarm/workers`.
`kazma swarm worker spawn <name> <role> [--model --provider --type]`	`POST /api/swarm/workers/spawn`.
`kazma swarm worker remove <name>`	`DELETE /api/swarm/workers/{name}`.

6.2 أنماط الإرسال

الأمر الفرعي	`type`	الوصف
`kazma swarm dispatch <worker> <prompt> [--context C]`	`dispatch`	عامل واحد.
`kazma swarm broadcast <prompt> [--context C]`	`broadcast`	جميع العمّال.
`kazma swarm consult <prompt> --workers a,b [--context C]`	`consult`	آراء متوازية + تركيب.
`kazma swarm pipeline --workers a,b,c <prompt>`	`pipeline`	مراحل مرتّبة + لوحة مشتركة.
`kazma swarm fanout --workers a,b <prompt> [--aggregation strategy]`	`fan_out`	توازٍ + تجميع.

# Dispatch one task to the "researcher" worker
kazma swarm dispatch researcher "Summarize today's oil prices"

# Fan out to three workers and vote on the result
kazma swarm fanout --workers a,b,c --aggregation vote "Best API design?"

# Run the standard pipeline
kazma swarm pipeline --workers researcher,refiner,builder,validator "Build a CLI tool"

6.3 المهام، المقاييس، الموثوقية

الأمر الفرعي	الوصف
`kazma swarm history [--type --status --page --page-size]`	`GET /api/swarm/tasks` (مُقسَّم إلى صفحات).
`kazma swarm task <id>`	`GET /api/swarm/tasks/{id}`.
`kazma swarm metrics [--worker W]`	`GET /api/swarm/workers/{W}/metrics` (أو `/metrics/all`).
`kazma swarm start` / `kazma swarm stop`	`POST /api/swarm/start` / `/stop`.
`kazma swarm approve <task_id>`	`POST /api/swarm/tasks/{id}/approve` (نقطة فحص الموافقة البشرية في الحلقة HITL).
`kazma swarm reject <task_id>`	`POST /api/swarm/tasks/{id}/reject`.
`kazma swarm circuit-breaker [worker] [--reset]`	`GET /api/swarm/circuit-breakers` لكل عامل، أو `POST .../reset`.

7. `kazma update`

تحديث ذاتي (update.py). الأعلام: --check/-c (تشغيل تجريبي)، --force/-f، --yes/-y، --help/-h. يكتشف نوع التثبيت تلقائيًا عبر pip show (“Editable project location”):

تثبيت عبر pip → يستعلم عن PyPI (https://pypi.org/pypi/kazma/json) ويُشغّل pip install --upgrade kazma.
تثبيت عبر git → git fetch، يفحص git log HEAD..origin/main، ثم git pull origin main + pip install -e ..

kazma update --check     # dry-run: show available update
kazma update --yes       # apply without prompting

8. `kazma hub` — مركز المهارات (مجموعة Click)

الشجرة الفرعية الوحيدة القائمة على Click (kazma_core/hub/cli.py:104). خيارات المجموعة: --registry-path (متغير البيئة KAZMA_HUB_DB، افتراضي ~/.kazma/hub/registry.db)، --hub-url (متغير البيئة KAZMA_HUB_URL، افتراضي https://hub.kazma.ai).

الأمر الفرعي	الوصف
`kazma hub register <path>`	تسجيل مهارة محلية.
`kazma hub search [query] [--capabilities --tags --author]`	البحث في السجل.
`kazma hub install <skill_id>`	تثبيت مهارة.
`kazma hub list`	سرد المهارات المثبّتة.
`kazma hub info <skill_id>`	عرض تفاصيل المهارة.
`kazma hub validate <path> [--json]`	التحقق من بيان مهارة (manifest).
`kazma hub uninstall <skill_id>`	إزالة مهارة.
`kazma hub submit <path> [--json --source-url]`	إرسال `POST` إلى `{hub_url}/api/v1/skills/submit`.
`kazma hub status <submission_id> [--json]`	حالة الإرسال.
`kazma hub badge <skill_ref> [--json]`	عرض شارة الاعتماد.
`kazma hub certified [--json]`	سرد المهارات المُعتمدة.
`kazma hub stats [--json]`	إحصاءات السجل.
`kazma hub check-certification <path> [--json]`	فحص مهارة مقابل معايير الاعتماد.
`kazma hub sign <path> [--secret]`	توقيع HMAC-SHA256 لملف نقطة الدخول `.py` داخل البيان (manifest). يتطلب `KAZMA_SECRET`. راجع المهارات وMCP والأدوات.

# Sign a skill (writes checksum + signature into skill_manifest.yaml)
KAZMA_SECRET=... kazma hub sign ./my-skill

# Search and install
kazma hub search "oil pricing" --capabilities mcp
kazma hub install oil-pricing-pro@1.2.0

9. `kazma-tui`

يُطلق واجهة Textual الطرفية (TUI) (kazma_tui.app:main ← KazmaTUI().run()). التبويبات: لوحة التحكم، الدردشة، الملفات، التتبعات، السرب، الإعدادات. يُهيّئ نسخًا مفردة (singletons) من ModelRegistry/SwarmEngine إذا أُطلق مستقلًا. يتضمّن نافذة منبثقة للموافقة البشرية في الحلقة (HITL) (widgets/hitl_modal.py).

kazma-tui
# or: python -m kazma_tui

10. `kazma-web`

اسم مستعار لإطلاق خادم واجهة الويب FastAPI مباشرةً (kazma_ui.app:main). افتراضي 127.0.0.1:8000؛ يُحذّر إذا الربط على 0.0.0.0 بدون KAZMA_SECRET (app.py:900-906).

kazma-web

11. أوامر الشرطة المائلة (داخل المحادثة)

تُكتَب هذه داخل محادثة متصلة (تيليجرام/ديسكورد/سلاك/الويب). مُعرَّفة في kazma-gateway/.../slash_commands.py.

الأمر	الوصف
`/help`	سرد الأوامر حسب الفئة.
`/reset`	مسح المحادثة (يُعالَج في `graph.py:196`).
`/status`	نظرة عامة على صحة البوابة.
`/model` أو `/models`	مُحدِّد النماذج التفاعلي (لوحة مفاتيح تيليجرام المضمّنة).
`/memory`	إحصاءات نظام الذاكرة.
`/cost`	إنفاق الرموز خلال الجلسة.
`/replay list \| <iter> \| compare <a> <b> \| clear`	السفر عبر الزمن.
`/config show \| model <n> \| personality <n> \| memory on\|off \| tools list \| tools toggle <n> \| export`	معالج الإعداد.
`/personality`	تفويض إلى `/config personality`.
`/context`	استخدام رموز نافذة السياق.
`/undo`	كعب (Stub) — غير مُنفّذ.
`/edit`	كعب (Stub) — غير مُنفّذ.
`hitl approve	deny <thread_id>`
`/swarm`	تنسيق السرب (مُسجَّل على تيليجرام؛ مُعالِج تفاعلي).

ملاحظة التكافؤ: يتجاهل نص /help كلاً من /hitl و/swarm رغم أن كليهما يعمل. دالة setMyCommands في تيليجرام تُسجّل /swarm لكنها لا تُسجّل /hitl. يحجز ديسكورد الأوامر ذات البادئة / لنفسه، لذا يستقبلها كاظمة كنص عادي. راجع البوابات والمنصات.

12. رموز الخروج

الرمز	المعنى
`0`	نجاح.
`1`	فشل عام / خادم غير قابل للوصول (تطبع أوامر swarm وgateway `Server not running. Start with: kazma serve` وتخرج برمز `1` عندما لا يكون خادم واجهة الويب قيد التشغيل — ابدأه أولًا عبر `kazma serve`).
`2`	خطأ في الوسيط/الاستخدام (Click، الشجرة الفرعية `kazma hub` فقط).

أوامر swarm وgateway هي عملاء REST: تخرج برمز غير صفري كلما لم يكن خادم واجهة الويب قيد التشغيل. ابدأ الخادم دائمًا (kazma serve) قبل استدعائها.

ملاحظات تدقيق التوثيق

نص --help يطبع “Kazma CLI v0.2.0” (main.py:75) بينما pyproject.toml هو 0.3.0. انحراف معروف.
kazma hub هي الشجرة الفرعية الوحيدة القائمة على Click. جميع الأوامر الأخرى تستخدم تحليلًا يدويًا للمُعاملات argv — وقد يكون ترتيب الأعلام وسلوك --help أقلّ انتظامًا من واجهة سطر أوامر قائمة على Click بالكامل.
/undo و/edit كبوبن (stubs) (slash_commands.py:257, 267) — حاضران في القائمة لكنهما صراحةً “غير مُنفّذين بعد”.

مرجع واجهة سطر الأوامر (CLI)

1. نقاط الدخول

2. kazma — الشجرة ذات المستوى الأعلى

2.1 kazma (بلا وسائط)

2.2 kazma status

2.3 kazma serve [port]

2.4 kazma wizard

2.5 kazma docs

3. kazma completion

4. kazma project

5. kazma gateway

5.0 العلم --port (swarm / gateway)

6. kazma swarm