CLI pdfx : un seul catalogue, appelé depuis votre terminal
La CLI pdfx envoie les mêmes requêtes multipart que curl vers l’API PDF123 ou votre propre pdfx-server, et ajoute l’exécution par lots, les mots de passe par fichier et des codes de sortie exploitables par un script.

PDF123 est le nom du produit. pdfx est ce même catalogue d’opérations enveloppé pour un shell : il construit la requête multipart que curl aurait construite, l’envoie à l’URL de base d’API que vous choisissez et écrit le résultat à côté de vos fichiers. Fusionner, Compresser, OCR et le reste du catalogue s’appellent ainsi.
Ce qu’envoie réellement un appel
pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base vaut https://pdf123.xyz par défaut, et --api-key (ou la variable d’environnement PDFX_API_KEY) est facultatif : le catalogue anonyme fonctionne donc sans clé. Pointez la base vers http://127.0.0.1:8080 pour votre propre pile docker-compose. Il n’y a pas de second protocole en dessous : la CLI est un client de la surface REST documentée sur Développeurs, et ses noms d’opérations correspondent aux outils du portail et au document OpenAPI à /v1/openapi.json.
Le catalogue se découvre sans quitter le terminal. pdfx list affiche tous les outils et pdfx describe add-stamp affiche les champs et les valeurs par défaut d’un outil, soit la même définition que le portail rend sous forme de formulaire.
Exécutions par lots et les options que curl vous oblige à écrire
Donnez plusieurs entrées à un outil mono-fichier et il les exécute comme un lot dans le répertoire -o, en affichant une ligne input -> saved par fichier. Les échecs vont sur stderr et les fichiers restants aboutissent quand même : un PDF défectueux dans un dossier de factures n’interrompt donc pas l’exécution. --concurrency <n> détermine combien de fichiers sont traités en parallèle (2 par défaut).
-o accepte un fichier ou un répertoire et n’écrase jamais un fichier existant : dans un répertoire, il utilise le nom que donne le serveur. C’est important quand le serveur nomme le résultat d’après l’entrée ; sans cela, une exécution écraserait le PDF que vous venez de téléverser.
Les entrées chiffrées sont ouvertes avant la requête, pas par l’outil : --input-password couvre tous les fichiers de l’exécution, et --password-for report.pdf=secret définit le mot de passe d’un fichier et peut être répété, * représentant les autres. Un lot mêlant fichiers verrouillés et ouverts ne demande donc aucun tri manuel. --json imprime { path, contentType, bytes } par résultat, ou [{ input, ok, path | error, reason }] pour un lot, afin qu’un script puisse analyser le déroulement au lieu d’extraire les lignes lisibles par un humain.
Des codes de sortie sur lesquels un script peut brancher
0 signifie succès, 1 qu’une requête a échoué (dans un lot : au moins un fichier), 2 est une erreur d’usage où rien n’a été téléversé, et 130 que vous avez interrompu la commande et que la requête en cours a été annulée. Les échecs impriment des lignes reason:, code: et hint: sous le message lorsqu’elles sont disponibles, et c’est là-dessus qu’un script doit s’appuyer, pas sur la prose.
Un code de sortie se lit facilement de travers. Un outil qui ne trouve rien à renvoyer sort avec un code non nul et code: no_content au lieu d’écrire un fichier vide : pdf-to-csv sur un PDF sans tableaux est donc un échec, pas un CSV de zéro octet.
Où vont les octets
Les fichiers sont téléversés vers l’URL de base d’API, traités là-bas, puis supprimés dès que la réponse est envoyée. C’est le même contrat que le formulaire du navigateur : la CLI change le client, pas la destination. Pour les documents qui ne doivent pas quitter votre réseau, exécutez vous-même un pdfx-server et pointez --api-base vers lui, ce qui est traité sur Auto-hébergement.
Aucun mode hors ligne ne sert de repli : si la base est injoignable, la commande échoue. pdfx est un client réseau qui se trouve être agréable dans un shell, pas un moteur PDF local.
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 : une tâche humaine ponctuelle reste donc mieux servie par le portail (Compresser, OCR et le reste du catalogue), et tout ce qui exigerait sa propre arborescence d’interface recréerait le problème de dérive décrit dans Une même opération, quatre clients.
Les agents obtiennent les mêmes formes grâce à la compétence publiée à /skills/pdf123.md, qui documente intégralement les requêtes de fusion et de pipeline. Pour réessayer sans risque des POST qui modifient l’état, envoyez un Idempotency-Key ; la CLI fait toujours une requête par invocation, donc cet en-tête revient à ce qui la réessaie (Idempotency-Key : réessais sûrs pour les tâches PDF). Clés, limites de débit et codes d’erreur sont sur Développeurs.