مرجع أوامر CLI

كل أمر ومعامل وخيار وافتراض في SubFT متحقق منه مقابل المصدر.

الخيارات العامة

ضع الخيارات العامة قبل الأمر. يتوفر --help تلقائياً لكل أمر ومجموعة. تعني الشرطة في افتراض المعامل أنه مطلوب، وتعني None حذف معامل اختياري. تستخدم الخيارات القابلة للتكرار .... تصف تعبيرات أنواع Python قيود المسارات والاختيارات الفعلية في Click وليست نصاً لإدخاله. اتبع مثال CLI للمدخلات والمعرّفات الفعلية.

الأمثلة أوامر مستقلة وليست تسلسلاً للتنفيذ. أنشئ أولاً المدخل التجريبي وصادق باستخدام وصفة CLI. يحمل متغير الصدفة operation_id المعرّف الفعلي الملتقط هناك. تستخدم أمثلة التسجيل ملفك demo/speech.wav من إعداد Python.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--version`	`bool`	`False`	—	`False`	عرض الإصدار المثبت والخروج.
`--json`	`bool`	`False`	—	`False`	كتابة مستند JSON واحد بإصدار محدد إلى stdout؛ تبقى الأسئلة والتشخيصات على stderr. لا يعطل ذلك الأسئلة.
`--yes`	`bool`	`False`	—	`False`	تعطيل الأسئلة والموافقة على الخصم والمزامنة المراجعة والاستبدال والكتابة فوق الملفات. تفشل الخيارات الملتبسة.

اختيارات إخراج الترجمة

هذه اختيارات --output-target المسجلة والمتحقق منها مقابل مصدر CLI. تحدد تنسيق الترجمة ومكانها المحلي؛ يختار --json غلاف الأتمتة بصورة مستقلة.

JSON

[
  "external_srt",
  "external_vtt",
  "external_ass",
  "embedded"
]

الاختيار	المعنى
`external_srt`	كتابة ملف ترجمة SRT خارجي مرافق.
`external_vtt`	كتابة ملف ترجمة WebVTT خارجي مرافق.
`external_ass`	كتابة ملف ترجمة ASS خارجي مرافق.
`embedded`	تضمين مسارات الترجمة المحددة في نسخة وسائط محلية باستخدام FFmpeg.

المصادقة والمشاريع

`subft login`

التحقق من رمز API وتخزينه لبوابته. استخدم الإدخال المخفي أو البيئة المحمية.

نص

subft login

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.
`--token`	`str`	`None`	—	`False`	رمز API لتسجيل الدخول؛ تجنب كشفه في سجل الأوامر باستخدام SUBFT_API_TOKEN أو الإدخال المخفي.

المتطلب: حساب ورمزه النشط؛ الصقه في الإدخال المخفي.

مثال:

Shell

subft login

`subft logout`

إزالة الرمز المحفوظ محلياً فقط. تبقى مصادقة البيئة نشطة؛ إلغاء الرمز على الخادم منفصل.

نص

subft logout

المتطلب: تهيئة محلية لإزالتها؛ لا يحدث إلغاء على الخادم.

مثال:

Shell

subft logout

`subft project bind`

ربط ملف أو مجلد محلي بمشروع محفوظ مناسب. الارتباطات ذاكرة مؤقتة قابلة للحذف وليست مزامنة للجرد.

نص

subft project bind PATH

المعامل	النوع	الافتراض	المعنى
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--project-id`	`str`	`None`	—	`False`	معرّف مشروع صريح. استخدمه عند صلاحية عدة ارتباطات مخزنة أو الحاجة إلى اختيار دون تدخل.
`--create`	`bool`	`False`	—	`False`	إنشاء مشروع فارغ جديد وربطه بوضع يطابق المسار المحلي. لا تجمعه مع --project-id.
`--name`	`str`	`None`	—	`False`	اسم العرض المستخدم مع --create؛ وإلا يوفر المسار المحلي اسماً افتراضياً.
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

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

مثال:

Shell

subft project bind demo/sample.srt --create --name docs-binding-example

`subft project bindings`

قراءة الارتباطات المخزنة دون تحقق من الخادم أو مصادقة. يرشح PATH الاختياري القائمة المحلية.

نص

subft project bindings [PATH]

المعامل	النوع	الافتراض	المعنى
`path`	`click.Path(path_type=Path)`	`None`	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

المتطلب: مسار المدخل التجريبي؛ افحص الارتباطات المخزنة للبوابة والحساب الحاليين.

مثال:

Shell

subft project bindings demo/sample.srt

`subft project forget`

إزالة ارتباطات محلية ضمن نطاق البوابة والحساب؛ قبول المسارات المفقودة وعدم حذف مشاريع الخادم أو أرشفتها.

نص

subft project forget PATH

المعامل	النوع	الافتراض	المعنى
`path`	`click.Path(path_type=Path)`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--project-id`	`str`	`None`	—	`False`	معرّف مشروع صريح. استخدمه عند صلاحية عدة ارتباطات مخزنة أو الحاجة إلى اختيار دون تدخل.
`--all`	`bool`	`False`	—	`False`	نسيان كل الارتباطات المخزنة لهذا المسار المحلي ضمن نطاق البوابة والحساب الحاليين.
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: ارتباطات مخزنة للمسار التجريبي. راجع التأكيد؛ تُحذف الذاكرة المحلية فقط.

مثال:

Shell

subft project forget demo/sample.srt --all

`subft project sync`

فحص الإدخال المحلي بالكامل ومطابقة جرد المشروع. تمنع أخطاء الفحص إرسال جزء فقط؛ يتطلب التطبيق القديم معاينة جديدة.

نص

subft project sync PATH

المعامل	النوع	الافتراض	المعنى
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--preview`	`bool`	`False`	—	`False`	فحص الجرد ومقارنته دون إضافة وسائط أو استبدالها. قد ينشئ حل المشروع مشروعاً طلبته صراحةً أو يخزن ارتباطه.
`--include-hidden`	`bool`	`False`	—	`False`	تضمين العناصر التي تبدأ بنقطة أثناء فحص المجلد؛ تبقى الروابط الرمزية مستبعدة.
`--project-id`	`str`	`None`	—	`False`	معرّف مشروع صريح. استخدمه عند صلاحية عدة ارتباطات مخزنة أو الحاجة إلى اختيار دون تدخل.
`--create`	`bool`	`False`	—	`False`	إنشاء مشروع فارغ جديد وربطه بوضع يطابق المسار المحلي. لا تجمعه مع --project-id.
`--name`	`str`	`None`	—	`False`	اسم العرض المستخدم مع --create؛ وإلا يوفر المسار المحلي اسماً افتراضياً.
`--media-id`	`str`	`None`	—	`False`	لمشاريع الملفات فقط: الوسيط الذي يُستبدل عندما تشترك عدة وسائط في اسم الملف. بدونه تتوقف المزامنة وتعرض معرّفاتها.
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: ارتباط مشروع المدخل التجريبي المنشأ في الوصفة. المعاينة مجانية ولا تعتمد عملاً بالذكاء الاصطناعي.

مثال:

Shell

subft project sync demo/sample.srt --preview

`subft status`

التحقق من بيانات الاعتماد الفعلية والبوابة؛ لا تُحفظ تجاوزات البيئة.

نص

subft status

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: رمز فعّال للبوابة المختارة.

مثال:

Shell

subft status

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

يتطلب تحضير المصادر وصولاً للحساب ومشروعاً متزامناً والملفات الأصلية. يحتاج اعتماد عمل AI إلى رصيد. تبقى المخرجات الناجحة المحفوظة قابلة للتنزيل؛ يحتاج apply أيضاً إلى الوجهة المحلية والارتباط المناسبين. تسمي قيم الاستخدام المكتوبة بأحرف كبيرة المعاملات؛ احصل على المعرّفات من الاستجابات دون تخمين.

`subft operation apply`

الانتظار عند الحاجة واختيار نواتج ناجحة محفوظة وكتابة المخرجات المحلية وتسجيلها. لا تتاح المدخلات الفاشلة؛ يحتاج التصدير الجزئي إلى موافقة صريحة.

نص

subft operation apply OPERATION_ID PATH

المعامل	النوع	الافتراض	المعنى
`operation_id`	`str`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--output-target`	`click.Choice(list(OUTPUT_TARGETS), case_sensitive=False)`	`None`	—	`False`	اختيار external_srt أو external_vtt أو external_ass أو embedded. يستخدم الحذف تفضيل الحساب؛ والافتراض دون تدخل هو external_srt.
`--content-id`	`str`	`()`	...	`False`	توفير مصدر مؤهل واحد مع supply؛ يقبل apply تكرار محددات عناصر المصدر لاختيار مجموعة نتائج.
`--artifact-id`	`str`	`()`	...	`False`	اختيار مرحلة ناجحة وثابتة محددة؛ كرره لعدة نواتج مراحل.
`--replace`	`str`	`()`	...	`False`	تستبدل أزواج ARTIFACT_ID=ASSET_ID أصول ترجمة فعلية مضمّنة ومفحوصة في الوسائط نفسها؛ وإلا يضيف embedded مسارات.
`--allow-partial`	`bool`	`False`	—	`False`	السماح بنتائج ناجحة من عمليات فاشلة أو ملغاة. يتطلب التصدير الجزئي دون تدخل --yes أيضاً ويبقى رمز الخروج غير صفري.
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: معرّف العملية الملتقط ونواتجها الناجحة المحفوظة ومسار المدخل التجريبي المرتبط الأصلي. راجع موافقة الكتابة فوق الملفات.

مثال:

Shell

subft operation apply "$operation_id" demo/sample.srt \
    --output-target external_srt

`subft operation start`

فحص الوسائط المتزامنة وتحضير المصادر والتقدير وتأكيد الخصم والاعتماد والتوفير. انتظر أو انفصل بعد القبول؛ التصدير منفصل.

نص

subft operation start PATH

المعامل	النوع	الافتراض	المعنى
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--lang`	`str`	`None`	—	`True`	رمز اللغة الهدف مطلوب. تنتمي خيارات لغة المصدر إلى الخطة التفاعلية أو افتراضات الخادم.
`--wait / --detach`	`bool`	`True`	—	`False`	انتظار معالجة الخادم افتراضياً؛ يعيد --detach التحكم بعد قبول المصادر. لا يصدر أي منهما ملفات.
`--include-hidden`	`bool`	`False`	—	`False`	تضمين العناصر التي تبدأ بنقطة أثناء فحص المجلد؛ تبقى الروابط الرمزية مستبعدة.
`--project-id`	`str`	`None`	—	`False`	معرّف مشروع صريح. استخدمه عند صلاحية عدة ارتباطات مخزنة أو الحاجة إلى اختيار دون تدخل.
`--create`	`bool`	`False`	—	`False`	إنشاء مشروع فارغ جديد وربطه بوضع يطابق المسار المحلي. لا تجمعه مع --project-id.
`--name`	`str`	`None`	—	`False`	اسم العرض المستخدم مع --create؛ وإلا يوفر المسار المحلي اسماً افتراضياً.
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: الملف التجريبي المتزامن ورصيد كافٍ وموافقة صريحة على التقدير.

مثال:

Shell

subft operation start demo/sample.srt --lang de --detach

`subft operation supply`

استئناف مصادر awaiting_client أو awaiting_retry المؤهلة في العملية المعتمدة نفسها. يتطلب استرداد فشل المعالجة النهائي عملية جديدة.

نص

subft operation supply OPERATION_ID PATH

المعامل	النوع	الافتراض	المعنى
`operation_id`	`str`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.
`path`	`click.Path(exists=True, file_okay=True, dir_okay=True, path_type=Path)`	—	جذر محلي أو مسار أو مسار POSIX نسبي. تستبعد أدوات الفحص الروابط الرمزية؛ أبق المسارات داخل الجذر المختار.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--content-id`	`str`	`None`	—	`False`	توفير مصدر مؤهل واحد مع supply؛ يقبل apply تكرار محددات عناصر المصدر لاختيار مجموعة نتائج.
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: عملية تسجيل مقبولة ذات تحضير مؤهل وملف WAV المحلي نفسه. تزوّد الإعادة العمل الموجود ولا تعيد بدء مراحل ذكاء اصطناعي نهائية.

مثال:

Shell

subft operation supply "$operation_id" demo/speech.wav

`subft operation watch`

إعادة الاتصال بحالة العملية المعتمدة مع أحداث فورية واستعلام HTTP. يفصل Ctrl-C دون إلغاء العمل المقبول.

نص

subft operation watch OPERATION_ID

المعامل	النوع	الافتراض	المعنى
`operation_id`	`str`	—	معرّف العملية التي تم اعتمادها؛ احتفظ به قبل المغادرة أو إعادة محاولة التحضير.

الخيار	النوع	الافتراض	التكرار	مطلوب	المعنى
`--api-url`	`str`	`None`	—	`False`	تجاوز بوابة هذا الاستدعاء، ويمكن توفيره عبر SUBFT_API_URL. لا تُرسل بيانات اعتماد محفوظة إلى بوابة أخرى.

المتطلب: معرّف العملية الملتقط وصلاحية مشروعها.

مثال:

Shell

subft operation watch "$operation_id"

الإعداد والكتابة المحلية

يتجاوز SUBFT_API_URL وSUBFT_API_TOKEN القيم المحفوظة لاستدعاء واحد. يتقدم --api-url على عنوان البيئة؛ ويختار --token بيانات الدخول صراحةً. يرتبط الرمز المحفوظ ببوابته. تحفظ المصادقة في $XDG_CONFIG_HOME/subft/config.json أو ~/.config/subft/config.json، والارتباطات في $XDG_STATE_HOME/subft/projects.json أو ~/.local/state/subft/projects.json. تستخدم مجلدات وملفات POSIX صلاحيات 0700/0600؛ الرموز محمية بالصلاحيات وليست مشفرة.

تستخدم مخرجات SRT/VTT/ASS الخارجية مسارات نسبية مقترحة من الخادم وملفات مؤقتة في المجلد نفسه واستبدالاً ذرياً. تحتاج الملفات الموجودة المختلفة إلى موافقة على الكتابة فوقها مرفوضة افتراضياً؛ تكون المخرجات المطابقة آمنة للتكرار. يحافظ التضمين على المسارات الأخرى ويتطلب FFmpeg ويرفض وجود <media>.bak ويتحقق من المسارات قبل تسجيل الأصول الفعلية. يحتفظ فشل التسجيل بالملف المتحقق منه والنسخة الاحتياطية؛ لا تعيد محاولة التسجيل داخل العملية الدمج. تحتاج النسخة الاحتياطية غير المحسومة إلى مراجعة يدوية. يكتشف استدعاء جديد الجرد كالمعتاد.

راجع عقود JSON والخروج واسترداد التحضير والاسترداد بعد الفشل النهائي.