pdfx: سطر أوامر PDF123

كيف أثبّت pdfx؟#

ثبّت الحزمة على مستوى النظام للحصول على الأمر pdfx. أو شغّله مرة واحدة دون تثبيت.

npm install -g @pdf123/cli
pdfx --version

npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf
bunx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

يعمل أيضًا bun add -g @pdf123/cli وpnpm add -g @pdf123/cli. ولا يلزم تثبيت أي شيء آخر.

كيف أبدأ؟#

تعرض هذه الأوامر الستة الأنماط الشائعة.

pdfx list                                          # every tool; --category security for one category
pdfx describe watermark                            # a tool's fields and defaults
pdfx merge a.pdf b.pdf -o merged.pdf
pdfx compress *.pdf -o compressed/                 # several files: one result per file
pdfx watermark in.pdf --watermarkText DRAFT
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf

كيف أشغّل أي أداة؟#

الوسيط الأول هو معرّف الأداة، ثم ملفات الإدخال ثم خيارات الأداة. كل خيار في الأداة هو راية (flag)، تُكتب باسم حقل API (--pageNumbers) أو بنمط kebab (--page-numbers). ويمكن أن يأتي الرقم السالب بعد رايته بمسافة، كما في --rotation -90، أو بعد علامة يساوي.

pdfx <tool> [files...] [--<field> <value>]...

استخدم pdfx list لعرض الأدوات. وهو يقبل --category أو --group، و--query مع كلمات للبحث. واستخدم pdfx describe <tool> لترى نقطة النهاية والمدخلات المقبولة وهل تعمل الأداة كدفعة، وكل حقل مع قيمته الافتراضية وقيمه المسموح بها. إذا كان معرّف الأداة مجهولًا ظهرت اقتراحات، وإذا كُتب خطأً أنهى الأمر عمله بالرمز 2.

أي الأوامر يقابل أي صفحة أداة؟#

كيف أعالج ملفات كثيرة دفعة واحدة؟#

أعطِ عدة ملفات لأداة ذات ملف واحد فيشغّل pdfx دفعة. استخدم -o مع مجلد ينتهي بشرطة مائلة. تعمل الأداة مرة لكل ملف، وملفان في وقت واحد افتراضيًا. غيّر ذلك بالخيار --concurrency.

pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

يطبع pdfx سطرًا واحدًا، input -> saved، عند انتهاء كل ملف. ويُبلَّغ عن الملف الفاشل في مجرى الأخطاء القياسي وتنتهي بقية الملفات. اضغط Ctrl-C مرة واحدة لإيقاف الطلب الجاري؛ وتبقى الملفات المحفوظة سلفًا. ويؤدي Ctrl-C الثاني إلى الخروج فورًا بالرمز 130. ومع --idempotency-key k يرسل كل ملف k:<index>، ويعيد تكرار الطلب نفسه النتيجة الأولى خلال 24 ساعة.

والدفعة التي تستخدم أداة تُرجع تقريرًا، مثل get-info، لا تكتب أي ملفات من دون -o. بل تطبع التقارير مفهرسة بملف الإدخال.

كيف أسلسل الأدوات في طلب واحد؟#

يشغّل pdfx pipeline عدة أدوات في طلب واحد. كرّر --step لكل أداة. ولضبط الخيارات مرّر مصفوفة JSON عبر --steps.

pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf
pdfx pipeline in.pdf --steps '[{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' -o out.pdf

لا يمكن للخطوات استخدام أدوات تحتاج إلى ملف ثانٍ.

كيف أفتح ملفات PDF المحمية بكلمة مرور؟#

يفتح --input-password كل مدخل مشفّر أولًا. ويحدّد --password-for <file>=<password> كلمة مرور ملف واحد. ويمكن تكراره، ويشمل * كاسم ملف بقية الملفات. وهذا يناسب دفعة تخلط ملفات مقفلة وأخرى مفتوحة. في merge وimages-to-pdf يُفتح قفل كل ملف مسمّى على حدة قبل تشغيل الأداة.

pdfx compress locked.pdf --input-password secret -o out.pdf
pdfx compress report.pdf --password-for report.pdf=secret -o out.pdf
pdfx merge a.pdf b.pdf --password-for a.pdf=secret -o merged.pdf

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

كيف يعمل الإدخال والإخراج؟#

• المدخل - يقرأ من الإدخال القياسي، مرة واحدة في كل تشغيل. و-o - يكتب النتيجة في الإخراج القياسي.
• -o file.pdf يكتب ذلك الملف. و-o dir/ يكتب داخل مجلد. المجلد غير الموجود بعد يحتاج إلى الشرطة المائلة الأخيرة، لأن الاسم بدونها يُكتب ملفًا.
• من دون -o تُحفظ النتائج في المجلد الحالي باسم الملف الذي يحدّده الخادم.
• داخل المجلد لا يستبدل pdfx ملفًا موجودًا أبدًا؛ بل يختار اسمًا جديدًا. أما -o file.pdf الصريح فيستبدل ذلك الملف.
• اسم ملف -o يتعارض امتداده مع النتيجة، مثل ملف ZIP ناتج من split يُحفظ بامتداد .pdf، يُرفض بالرمز 2 مع code: output_mismatch، ولا يُكتب شيء.
• المخرَج الذي يتعذّر كتابته خطأ استخدام يُكتشف قبل رفع أي شيء.

cat in.pdf | pdfx compress - -o - > out.pdf

ماذا يطبع الخيار --json؟#

عند حفظ نتيجة، يطبع --json المسار ونوع المحتوى والحجم. وتطبع الأداة التي تُرجع تقريرًا التقرير نفسه. وتطبع الدفعة تقريرًا واحدًا بحالة لكل ملف.

{ "path": "one.pdf", "contentType": "application/pdf", "bytes": 1040 }

{
  "processed": 2,
  "unmatched": 0,
  "failed": 0,
  "files": [
    { "input": "/abs/a.pdf", "ok": true, "path": "comp/a.pdf", "contentType": "application/pdf", "bytes": 1040 }
  ]
}

الملف الفاشل فيه error وreason بدلًا من path وbytes. وأداة المرشِّح التي لا تجد تطابقًا تطبع { "matched": false }. ويطبع pdfx list --json صفوفًا فيها id وcategory وgroup وname وdescription وreturns وfiles وfilter.

ما الخيارات التي تنطبق على كل أداة؟#

ما رموز الخروج؟#

تطبع حالات الفشل أسطر reason: وcode: وhint: حين يوفّرها الخادم، ليتمكن النص البرمجي من التفرّع دون مطابقة النصوص. والأداة التي لا تجد ما تُرجعه، مثل pdf-to-csv على ملف PDF بلا جداول، تنتهي بالرمز 1 مع code: no_content بدلًا من كتابة ملف فارغ. الرموز مسرودة في رموز الأخطاء.

كيف أوجّه pdfx إلى خادمي الخاص؟#

عيّن PDFX_API_BASE، أو مرّر --api-base، على عنوان pdfx-server المستضاف ذاتيًا. وأضف PDFX_API_KEY إذا كان خادمك يتطلب مفتاحًا. راجع الاستضافة الذاتية.

export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

كيف أشغّل نقطة نهاية لا يعرفها CLI؟#

يرسل pdfx call طلبًا خامًا إلى معرّف عملية أو مسار /api/.... استخدم --field name=value لحقول النموذج و--file field=path للملفات الإضافية. وهو يرسل طلبًا واحدًا بالضبط ولا يتحقق من شيء محليًا، لذلك تُرفض كلمات المرور والدفعات.

pdfx call general/merge-pdfs a.pdf b.pdf -o merged.pdf
pdfx call /api/v1/misc/flatten in.pdf --field flattenOnlyForms=true -o flat.pdf

صفحات ذات صلة#

• نظرة عامة للمطوّرين مع REST API والمصادقة
• TypeScript SDK، المكتبة التي بُني عليها سطر الأوامر
• خوادم MCP لوكلاء الذكاء الاصطناعي
• مقال "pdfx CLI: One Catalog, Called From Your Terminal" في مدونة PDF123

الأسئلة الشائعة#

هل يعمل pdfx دون اتصال بالإنترنت؟#

لا. يرفع pdfx كل ملف إلى PDF123 API أو إلى خادمك الخاص ويحفظ النتيجة محليًا، لذا يجب أن يكون عنوان API الأساسي قابلًا للوصول.

هل يحتاج pdfx إلى مفتاح API؟#

لا. يعمل الاستخدام المجهول. عيّن PDFX_API_KEY أو مرّر --api-key إذا كان خادمك يتطلب مفتاحًا. يُرسل المفتاح في الترويسة X-API-KEY.

أي إصدار من Node يحتاج إليه pdfx؟#

Node 20.3 أو أحدث، أو Bun.

هل سيستبدل pdfx ملفاتي؟#

ليس حين يكتب داخل مجلد: فلا يُستبدل ملف موجود أبدًا. أما إذا سمّيت ملف الإخراج بنفسك بـ -o file.pdf فسيُستبدل ذلك الملف، لذا اختر اسمًا جديدًا إن أردت الاحتفاظ بالأصل.

ماذا يحدث حين لا تجد أداة المرشِّح تطابقًا؟#

أدوات المرشِّح، التي تبدأ معرّفاتها بـ filter-، تمرّر الملف كما هو حين يتحقق شرطها. وحين لا يتحقق، يطبع pdfx الرسالة no match وينتهي بالرمز 0. وفي الدفعة يُحتسب مثل هذا الملف غير مطابق، لا فاشلًا.