CLI pdfx : local d’abord, cloud quand il le faut
pdfx traite les PDF en local par défaut. Activez le mode cloud avec une URL de base et une clé pour les API REST de PDF123, hébergées ou auto-hébergées.
PDF123 est le nom du produit. pdfx est la CLI courte qui s’adresse aux mêmes opérations. Le chemin par défaut est local : lire un fichier, exécuter l’opération via pdf-core, écrire une sortie. Aucun compte, aucune clé API, aucun téléversement.
Local d’abord : le fichier ne part jamais
Un appel typique ressemble à pdfx merge a.pdf b.pdf -o merged.pdf ou pdfx compress input.pdf. Le traitement s’exécute là où s’exécute le binaire. Cela convient aux tâches CI sur un exécuteur privé, aux scripts à côté d’un lot de factures et à tous les cas où envoyer le fichier à un tiers est la mauvaise réponse.
Le mode local n’est pas une fine surcouche qui transmettrait discrètement les octets ailleurs. La CLI partage le même registre d’opérations que le serveur (pdf_core::ops::run). Pour emprunter le chemin réseau, activez-le avec --cloud.
Les sous-commandes intégrées couvrent les opérations courantes : fusion, découpage, compression, rotation, extraction, OCR, conversion, protection, déverrouillage, filigrane et travaux associés. En local, la sortie va par défaut dans un fichier via -o / --output ; - écrit sur la sortie standard.
--cloud : le même catalogue en HTTP
Quand vous avez besoin de l’API hébergée (ou de votre propre pdfx-server), passez --cloud avec --api-base et --api-key (ou PDFX_API_KEY). Le mode cloud s’appuie sur curl et échoue si aucune clé API n’est définie. Exemple tiré de la compétence publiée :
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base vaut https://pdf123.xyz par défaut, l’API hébergée. Pour une pile Docker Compose locale, pointez-le plutôt vers http://127.0.0.1:8080. La CLI devient un client de la surface REST documentée sur Développeurs ; les noms d’opérations correspondent aux outils du portail et à OpenAPI (/v1/openapi.json).
Le mode cloud ne change pas ce que signifie une opération. La compression reste la compression de flux qpdf ; l’OCR renvoie toujours du texte Markdown par le chemin Rust, et non une couche intégrée à un PDF interrogeable. Les options héritées de la CLI qui correspondent à des paramètres OCR ignorés de l’époque Java (par exemple un champ languages) ne modifient pas ce contrat.
Pourquoi deux modes
Le mode local couvre la confiance hors ligne et l’absence de coût d’aller-retour. Le mode cloud couvre les plafonds de débit partagés, l’exécution d’opérations sur une machine où seuls la CLI et curl sont installés, et les équipes qui émettent déjà des clés API. Les agents peuvent aussi appeler la même base via MCP à /mcp ou la compétence fournie dans dist/skills/pdf-toolbox/SKILL.md. Les index de découverte comme /llms.txt aident les agents de codage à trouver les points de terminaison ; ce n’est pas un signal de classement pour Google.
Pour réessayer sans risque les POST qui modifient l’état via l’API, envoyez un Idempotency-Key (voir Idempotency-Key : réessais sûrs pour les tâches PDF). Le chemin cloud de la CLI reste une requête HTTP par invocation ; utilisez cet en-tête quand votre enveloppe réessaie.
Choisir un mode en pratique
Préférez le local quand les fichiers doivent rester sur l’exécuteur, quand le binaire pdfx et ses dépendances natives sont déjà installés sur la machine, et quand la latence vient de l’opération plutôt que du téléversement. Préférez le cloud quand les dépendances lourdes n’existent que sur le serveur, quand vous voulez les mêmes plafonds de débit et le même comptage que les autres clients de l’API, ou quand les agents détiennent déjà une clé API pour https://pdf123.xyz ou votre base auto-hébergée.
Ne mélangez pas les attentes : l’OCR local suit toujours le contrat de sortie Markdown de misc/ocr-pdf ; la compression cloud reste des flux qpdf, pas du sous-ensemblage de polices. Le changement de mode modifie l’endroit où l’opération s’exécute, pas la sémantique du catalogue.
Ce que la CLI n’est pas
pdfx n’est pas une interface graphique de bureau, ni une bibliothèque OCR embarquable à lier dans une autre application. C’est un client en ligne de commande pour les opérations PDF : local par défaut, HTTP sur demande. Les usages ponctuels au navigateur restent sur le portail (Compresser, OCR et le reste du catalogue). Une automatisation qui préfère un binaire peut rester sur pdfx.
Les comparaisons d’une même opération entre navigateur, curl, MCP et CLI sont esquissées dans Une même opération, quatre clients. Commencez par Développeurs pour les clés et OpenAPI, ou par Auto-hébergement si la base d’API doit être votre propre pile Docker Compose.