مرجع واجهة سطر الأوامر
مرجع واجهة سطر الأوامر في Apothem — جميع الأوامر الفرعية والرايات.
واجهة سطر الأوامر apothem هي الواجهة الأساسية للمُشغِّل لإدارة الملف
التعريفي المشترك ومحوّلات أُطُر العمل.
الرايات العامة
| الراية | الوصف |
|---|---|
--version | يطبع نسخة Apothem ويخرج |
--help | يطبع التعليمات الخاصة بالأمر |
الأوامر الفرعية
apothem install
يُثبّت محوّل إطار عمل من الملف التعريفي المشترك.
apothem install --harness <name|all> [--profile PATH] [--project PATH] [--dry-run] [--clean|--fresh] [--yes]| الخيار | الوصف |
|---|---|
--harness <name> | اسم محوّل إطار العمل (راجع القيم المرجعية أدناه). مطلوب. |
--profile PATH | المسار إلى ملف YAML للملف التعريفي المشترك. القيمة الافتراضية ~/.config/apothem/profile.yaml. |
--project PATH | جذر المشروع لأُطُر العمل ذات نطاق المشروع. |
--dry-run | معاينة التثبيت دون كتابة ملفات. |
--clean، --fresh | بداية نظيفة اختيارية: نسخ حالة التثبيت السابقة احتياطيًا ثم إزالتها (~/.claude، و~/.codex، و~/.agents، و~/.config/apothem) قبل التثبيت. |
--yes | تخطّي التأكيد لكل هدف أثناء إزالة البداية النظيفة (مطلوب لتشغيلات --clean غير التفاعلية). |
قيم --harness المرجعية:
antigravity
claude-code
codebuddy
codex
cursor
gemini-cli
github-copilot
glm
hermes
kimi-code
kiro
open-claw
opencode
qwen-code
trae
windsurf
zedاستخدم --harness all --project <path> لاختيار المجموعة على مستوى السجلّ
كله. وتُحترَم قائمة exclude_harnesses في الملف التعريفي أثناء الاختيار
الدفعي في التثبيت/التحديث.
apothem update
يُعيد اشتقاق الإعداد الأصلي لمحوّل إطار عمل من الملف التعريفي المشترك الحالي.
apothem update --harness <name|all> [--profile PATH] [--project PATH] [--dry-run]| الخيار | الوصف |
|---|---|
--harness <name> | اسم محوّل إطار العمل. مطلوب. |
--profile PATH | المسار إلى ملف YAML للملف التعريفي المشترك. |
--project PATH | جذر المشروع لأُطُر العمل ذات نطاق المشروع. |
--dry-run | معاينة التحديث دون كتابة ملفات. |
يُعيد update تجسيد مُخرَجات إطار العمل. ولا يُرقّي محرّك Apothem
نفسه؛ حدِّث المحرّك عبر القناة التي ثبّتّه بها (مسار /plugin، أو npx،
أو سكربتات المُثبِّت والتحديث)، كما هو موضَّح في التحديث.
apothem uninstall
يزيل الإعداد الأصلي لمحوّل إطار عمل.
apothem uninstall --harness <name|all> [--project PATH] [--yes]| الخيار | الوصف |
|---|---|
--harness <name> | اسم محوّل إطار العمل. مطلوب. |
--project PATH | جذر المشروع لأُطُر العمل ذات نطاق المشروع. |
--yes | تخطّي مُطالَبة التأكيد. |
apothem verify
يتحقّق من أن الأهداف المُدارة لمحوّل إطار عمل موجودة وصالحة.
apothem verify --harness <name|all> [--profile PATH] [--project PATH]| الخيار | الوصف |
|---|---|
--harness <name> | اسم محوّل إطار العمل أو all. مطلوب. |
--profile PATH | ملف YAML للملف التعريفي المشترك الذي يُفحَص مدى أمانة التثبيت له. ومن دونه يكون الفحص بنيويًا بحتًا. |
--project PATH | جذر المشروع لأُطُر العمل ذات نطاق المشروع. |
من دون --profile يكون الفحص بنيويًا: يجب أن يكون كل هدف مُدار موجودًا
وصالحًا. ومع --profile يشترط الفحص الأمانةَ أيضًا، فيُخفِق التحقّق في
تثبيتٍ موجود لكنه انحرف عن ذلك الملف التعريفي — استخدمه للتأكّد من أن ملفًا
تعريفيًا بعينه مُثبَّت بأمانة.
رمز الخروج هو 0 عندما يُتحقَّق من إطار العمل (ويكون، مع
--profile، أمينًا له)، و1 عندما يكون هدفٌ مفقودًا أو غير
صالح، أو عندما يُمرَّر --profile ويكون التثبيت قد انحرف.
apothem status
يُبلِغ عن حالة التثبيت والتحقّق والانحراف لكل إطار عمل مُسجَّل.
apothem status [--profile PATH] [--project PATH]| الخيار | الوصف |
|---|---|
--profile PATH | الملف التعريفي المشترك الذي يُستخدَم خطَّ أساسٍ للانحراف. والملف التعريفي الافتراضي غير القابل للقراءة يُخفِّض الانحراف إلى unknown بدلًا من إجهاض المسح. |
--project PATH | جذر المشروع لأُطُر العمل ذات نطاق المشروع. ومن دونه تُبلِغ هذه الأُطُر عن needs-project. |
يقرن كل صفٍّ راية installed براية verified، وتجتمع
الرايتان في حالة الانحراف:
| الحالة | المعنى |
|---|---|
absent | لم يُثبِّت Apothem في إطار العمل هذا. |
in-sync | مُثبَّت ومطابق لخط أساس الملف التعريفي. |
drift | مُثبَّت لكنه لم يعد مطابقًا — عالِجه بـ apothem update. |
unknown | مُثبَّت، لكن تعذّرت قراءة الملف التعريفي الأساس. |
needs-project | أُبلِغ عن إطار عمل ذي نطاق مشروع من دون --project، فتعذّر تحديد هدفه. |
تُجيب installed عن السؤال «هل ثبّت Apothem هنا؟»، لا عن
«هل إطار العمل هذا موجود على الجهاز؟». وهي مبنيّة على مُنتَجات Apothem
نفسه — الكتلة المُدارة داخل مرساة التعليمات، والمحتوى تحت الشجرة الفرعية
.apothem/ التي يملكها Apothem — ولا تُبنى أبدًا على ملف يملكه
المورّد يكتبه إطار العمل لنفسه. وإطار العمل الذي يوجد دليل إعداده لكن
Apothem لم يمسّه قطّ يُبلِغ عن absent، والإطار الذي أُلغي
تثبيته يُبلِغ عن absent حتى وإن بقيت الأدلة المُفرَغة.
apothem profile
يُدير الملف التعريفي المشترك لـ Apothem.
apothem profile show [--profile PATH]
apothem profile init [--profile PATH] [--force]
apothem profile set <key> <value> [--profile PATH]
apothem profile edit [--profile PATH]| الأمر الفرعي | الوصف |
|---|---|
profile init | يُنشئ هيكلًا أوّليًّا مُصغَّرًا لملف تعريفي صالح وفق المخطط. |
profile show | يطبع الملف التعريفي المُحلَّل بصيغة JSON إلى stdout. ومع --json يتصدّر المستند الحقل schema_version. |
profile set <key> <value> | يضبط حقلًا في الملف التعريفي. تُخزَّن القيمة سلسلةً نصّية حرفية؛ فلا تُحوَّل الكلمات المجرّدة قسرًا، فتبقى no على هيئة "no" وتبقى 1.0 سلسلة نصّية، باستثناء true/false ومُدخَلات القوائم والخرائط الصريحة [...] / {...}. ويُتحقَّق من الملف التعريفي المُجمَّع عبر المخطط قبل كتابته. |
profile edit | يفتح الملف التعريفي في $EDITOR (ويرجع إلى المحرّر الافتراضي للمنصّة). |
يُوجِّه الخيار --profile PATH كلَّ أمر فرعي إلى ملف تعريفي بديل. والقيمة
الافتراضية ~/.config/apothem/profile.yaml.
apothem harnesses
يسرد محوّلات أُطُر العمل المُسجَّلة ويفحصها.
apothem harnesses list
apothem harnesses show <name>| الأمر الفرعي | الوصف |
|---|---|
harnesses list | يطبع جدولًا بكل محوّل مُسجَّل مع راية حالة تثبيته ومسار مُخرَجه. |
harnesses show <name> | يطبع الاسم وحالة التثبيت ومسار المُخرَج لمحوّل واحد. |
apothem doctor
يُشغّل تشخيصات النظام لتثبيت Apothem.
apothem doctorيطبع إصدار Apothem، ومُفسِّر Python، والمنصّة، ومسار الملف التعريفي المُحلَّل، وجدول حالة التثبيت لكل إطار عمل. ورمز الخروج هو 1 عندما يفشل أي فحص: ملف تعريفي غير صالح، أو إطار عمل مثبّت لا يجتاز التحقّق، أو أمر خطّاف مُسجَّل لا يمكن تشغيله، أو محوّل تعذّر تحميله أو استجوابه، أو سجلّ غير قابل للقراءة. ويُبلَّغ عن إطار العمل غير المثبّت ولا يُعدّ فشلًا، والملاحظات الإعلامية لا تغيّر رمز الخروج.
مرجع الأوامر والرايات المُولَّد
| Command | Flags | Description |
|---|---|---|
apothem backups prune | --dry-run, --format, --harness, --json, --keep, --no-color, --quiet, -q, --verbose, -v | Delete backup sets and install records beyond the newest N per harness. Keeps the newest N backup sets under ~/.apothem/backups/ for each selected harness, and the newest N install records per install root in its ledger under ~/.apothem/state/. A backup set that a kept record, or the latest install record of any install root, still references is never deleted, so rollback of the latest install still restores. |
apothem completion | — | Print a shell-completion script for SHELL to stdout. Supported shells: bash, zsh, fish, powershell. Every script is generated by Click's env-var completion protocol — PowerShell through the completion class registered above, since Click ships none natively. Enabling completion is opt-in: this command only prints the script — pipe or append it to the shell's completion file yourself (see --help). |
apothem diff | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Preview the pending configuration changes for a single harness. |
apothem doctor | --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Check the installed harnesses and the shared profile; exit 1 on any failure. Reports the engine version, Python, and platform; validates a present shared profile against the packaged schema; and, for every installed harness, runs the adapter's verify and starts each hook command the install registered with a no-op payload. A harness that is not installed is reported but is not a failure, so a machine with one healthy harness passes. Project-scope harnesses are checked when --project names their root. |
apothem harnesses list | --format, --json, --no-color, --quiet, -q, --verbose, -v | List all registered harness adapters. |
apothem harnesses show | --format, --json, --no-color, --quiet, -q, --verbose, -v | Show details for a specific harness adapter. |
apothem install | --clean, --fresh, --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Install a harness adapter configuration. |
apothem migrate-workspace | --dry-run, --format, --json, --no-color, --project, --quiet, -q, --verbose, -v | Migrate a legacy per-harness workspace into the shared .apothem layout. The base is the resolved --project root when supplied, otherwise the current working directory (the project-local default). Per-harness memory/contexts/learning stores union-merge into the shared store; a conflicting record is skipped, never overwritten; a legacy .plans tree moves under .apothem/plans; every consumed source is backed up first. The migration is idempotent. |
apothem profile edit | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Open the shared profile in the system editor. |
apothem profile init | --force, --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Create a schema-valid shared profile scaffold. |
apothem profile set | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Set a key in the shared profile. KEY is a dotted path that descends into the nested profile structure (identity.name, preferences.style, enforcement.sprints, harnesses.<harness>.preferences.style); a single key with no dot sets a top-level node. VALUE is stored as a literal string — bare words are not coerced (no stays "no", 2024-01-01 and 1.0 stay strings) — except true/false (the boolean enforcement flags) and explicit [...]/{...} list/map input. The fully-assembled profile is validated against the packaged schema BEFORE writing; an invalid set is refused with the standard diagnostic and the profile on disk is unchanged. |
apothem profile show | --format, --json, --no-color, --profile, --quiet, -q, --verbose, -v | Display the current shared profile. |
apothem quickstart | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v, --yes | Guided first run: ensure a profile, preview the writes, then install. Walks a new operator through the canonical path in one linear flow — create a starter profile if none exists (with a personalize nudge), preview the files each harness will write (project root vs your home directory), confirm, then install with the grouped capability-note output — and ends with the recommended next commands. --yes runs the whole sequence non-interactively; --format json emits one structured summary of every step. It composes the install building blocks; it does not duplicate them. Without --harness it asks which harness to install, so the first run writes one harness's configuration rather than all of them; all is an explicit choice. A run that cannot ask fails with a usage error before anything is written. |
apothem rollback | --format, --harness, --install-id, --json, --last, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Restore a harness to the state before its recorded install. |
apothem status | --format, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Report install, verify, and drift state for every registered harness. |
apothem uninstall | --format, --harness, --json, --no-color, --project, --quiet, -q, --verbose, -v, --yes | Remove a harness adapter configuration. |
apothem update | --dry-run, --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Re-install a harness adapter configuration from the current profile. |
apothem verify | --format, --harness, --json, --no-color, --profile, --project, --quiet, -q, --verbose, -v | Verify a harness adapter installation. Without --profile the check is structural: every managed target must be present and valid. With --profile the check additionally requires profile fidelity, so a present-but-drifted install fails verify — answering "is THIS profile faithfully installed?" rather than merely "does it exist?". |