pdfx CLI: पहले स्थानीय, क्लाउड जब ज़रूरत हो

PDF123 उत्पाद का नाम है। pdfx वह छोटा CLI है जो उन्हीं प्रचालनों से बात करता है। डिफ़ॉल्ट पथ स्थानीय है: फ़ाइल पढ़ें, pdf-core के ज़रिए कार्य चलाएँ, नतीजा लिखें। न खाता, न API की, न अपलोड।

पहले स्थानीय का मतलब है फ़ाइल कहीं नहीं जाती

आम कॉल ऐसी दिखती है: pdfx merge a.pdf b.pdf -o merged.pdf या pdfx compress input.pdf। प्रसंस्करण वहीं चलता है जहाँ बाइनरी चलती है। यह निजी रनर पर CI कार्यों, इनवॉइस के ढेर के पास पड़ी स्क्रिप्टों, और हर उस मामले में फ़िट बैठता है जहाँ किसी तीसरे पक्ष पर अपलोड करना गलत जवाब है।

स्थानीय मोड ऐसा पतला आवरण नहीं है जो चुपचाप बाइट्स कहीं और भेज दे। CLI वही प्रचालन-रजिस्ट्री साझा करता है जो सर्वर करता है (pdf_core::ops::run)। नेटवर्क पथ चाहिए तो --cloud के साथ उसमें प्रवेश करें।

अंतर्निहित उपादेश आम कार्यों को कवर करते हैं: मर्ज, विभाजन, संपीड़न, घुमाव, निष्कर्षण, OCR, रूपांतरण, सुरक्षा, अनलॉक, वॉटरमार्क और संबंधित काम। स्थानीय नतीजा डिफ़ॉल्ट रूप से -o / --output से फ़ाइल में जाता है; - stdout पर लिखता है।

--cloud वही कैटलॉग है, HTTP पर

जब आपको होस्टेड API चाहिए (या आपका खुद का pdfx-server), तो --cloud के साथ --api-base और --api-key दें (या PDFX_API_KEY)। क्लाउड मोड भीतर से curl माँगता है और बिना API की फेल हो जाता है। प्रकाशित स्किल से उदाहरण:

pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

--api-base बिना दिए डिफ़ॉल्ट https://pdf123.xyz रहता है, यानी होस्टेड API। स्थानीय Docker Compose स्टैक के लिए इसे http://127.0.0.1:8080 पर इंगित करें। CLI, Developers पर दर्ज REST सतह का क्लाइंट बन जाता है; प्रचालनों के नाम पोर्टल टूल और OpenAPI (/v1/openapi.json) से मेल खाते हैं।

क्लाउड मोड यह नहीं बदलता कि किसी प्रचालन का मतलब क्या है। Compress अब भी qpdf स्ट्रीम संपीड़न है; OCR अब भी Rust पथ से Markdown टेक्स्ट लौटाता है, खोजने-योग्य PDF परत नहीं। जो पुराने CLI फ़्लैग अनदेखे Java-कालीन OCR पैरामीटरों से मैप होते हैं (जैसे कोई languages फ़ील्ड), वे यह अनुबंध नहीं बदलते।

दो मोड क्यों हैं

स्थानीय, ऑफ़लाइन भरोसा और शून्य राउंड-ट्रिप लागत कवर करता है। क्लाउड, साझा दर-सीमाएँ, ऐसी मशीन पर प्रचालन चलाना जहाँ सिर्फ़ CLI और curl हैं, और वे टीमें कवर करता है जिनके पास पहले से API की हैं। एजेंट वही बेस /mcp पर MCP से, या dist/skills/pdf-toolbox/SKILL.md की स्किल से भी बुला सकते हैं। /llms.txt जैसे खोज-सूचकांक कोडिंग एजेंट को एंडपॉइंट ढूँढने में मदद करते हैं; वे Google रैंकिंग संकेत नहीं हैं।

API पर बदलाव करने वाले POST के सुरक्षित पुनः प्रयासों के लिए Idempotency-Key भेजें (Idempotency-Key: PDF कार्यों के सुरक्षित पुनः प्रयास)। CLI का क्लाउड पथ हर बुलावे पर अब भी एक HTTP अनुरोध है; जब आपका आवरण पुनः प्रयास करे, तब यह शीर्षलेख इस्तेमाल करें।

व्यवहार में मोड चुनना

स्थानीय तब चुनें जब फ़ाइलें रनर पर ही रहनी हों, जब pdfx बाइनरी और नेटिव निर्भरताएँ उस मशीन पर पहले से हों, और जब विलंबता पर अपलोड नहीं, प्रचालन हावी हो। क्लाउड तब चुनें जब भारी निर्भरताएँ सिर्फ़ सर्वर पर हों, जब आपको बाक़ी API क्लाइंट जैसी ही दर-सीमाएँ और मीटरिंग चाहिए, या जब एजेंट के पास पहले से https://pdf123.xyz या आपके स्वयं-होस्टेड बेस की API की हो।

अपेक्षाएँ न मिलाएँ: स्थानीय OCR अब भी misc/ocr-pdf के Markdown आउटपुट अनुबंध का पालन करता है; क्लाउड compress अब भी qpdf स्ट्रीम है, फ़ॉन्ट सबसेटिंग नहीं। मोड बदलने से यह बदलता है कि प्रचालन कहाँ चलता है, कैटलॉग का अर्थ नहीं।

CLI जो नहीं है

pdfx न डेस्कटॉप GUI है, न कोई एम्बेड करने योग्य OCR लाइब्रेरी जिसे आप दूसरे ऐप में जोड़ें। यह PDF प्रचालनों के लिए कमांड-लाइन क्लाइंट है: डिफ़ॉल्ट रूप से स्थानीय, पूछने पर HTTP। ब्राउज़र के एक-बारगी काम अब भी पोर्टल पर रहते हैं (Compress, OCR, और बाक़ी कैटलॉग)। जो स्वचालन बाइनरी पसंद करता है, वह pdfx पर रह सकता है।

ब्राउज़र, curl, MCP और CLI के आर-पार समान-प्रचालन तुलना वही प्रचालन, चार क्लाइंट में रेखांकित है। चाबियों और OpenAPI के लिए Developers से शुरू करें, या यदि API बेस आपका खुद का Docker Compose स्टैक होना चाहिए तो Self-host।