pdfx : la ligne de commande de PDF123

Comment installer pdfx ?#

Installez le paquet globalement pour obtenir la commande pdfx. Ou lancez-le une fois, sans installation.

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 et pnpm add -g @pdf123/cli fonctionnent aussi. Rien d'autre n'est à installer.

Comment démarrer ?#

Ces six commandes montrent les schémas courants.

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

Comment lancer un outil ?#

Le premier argument est l'identifiant de l'outil. Les fichiers d'entrée et les options de l'outil suivent. Chaque option d'un outil est un indicateur, écrit avec le nom du champ de l'API (--pageNumbers) ou en kebab-case (--page-numbers). Un nombre négatif peut suivre son indicateur après une espace, comme dans --rotation -90, ou après un signe égal.

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

Utilisez pdfx list pour voir les outils. La commande accepte --category ou --group, ainsi que --query avec des mots à rechercher. Utilisez pdfx describe <tool> pour voir le point de terminaison, les entrées acceptées, si l'outil fonctionne par lots, et chaque champ avec sa valeur par défaut et ses valeurs autorisées. Un identifiant d'outil inconnu reçoit des suggestions, et un identifiant mal saisi se termine avec le code 2.

Quelle commande correspond à quelle page d'outil ?#

Comment traiter plusieurs fichiers à la fois ?#

Donnez plusieurs fichiers à un outil à fichier unique et pdfx lance un lot. Utilisez -o avec un répertoire terminé par une barre oblique. L'outil s'exécute une fois par fichier, deux fichiers à la fois par défaut. Modifiez cela avec --concurrency.

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

pdfx affiche une ligne, input -> saved, à mesure que chaque fichier se termine. Un fichier en échec est signalé sur l'erreur standard et les autres fichiers vont quand même au bout. Appuyez une fois sur Ctrl-C pour interrompre la requête en cours ; les fichiers déjà enregistrés sont conservés. Un second Ctrl-C quitte immédiatement avec le code 130. Avec --idempotency-key k, chaque fichier envoie k:<index>, et une répétition de la même requête rejoue le premier résultat pendant 24 heures.

Un lot d'un outil qui renvoie un rapport, comme get-info, n'écrit aucun fichier sans -o. Il affiche les rapports classés par fichier d'entrée.

Comment enchaîner des outils en une seule requête ?#

pdfx pipeline lance plusieurs outils en une seule requête. Répétez --step pour chaque outil. Pour définir des options, passez un tableau JSON avec --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

Les étapes ne peuvent pas utiliser d'outils qui exigent un second fichier.

Comment ouvrir des PDF protégés par mot de passe ?#

--input-password ouvre d'abord toutes les entrées chiffrées. --password-for <file>=<password> définit le mot de passe d'un seul fichier. L'option peut être répétée, et * comme nom de fichier couvre tous les autres. C'est pratique pour un lot qui mélange fichiers verrouillés et ouverts. Pour merge et images-to-pdf, chaque fichier nommé est déverrouillé séparément avant l'exécution de l'outil.

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

Les mêmes options fonctionnent dans un pipeline. Pour retirer définitivement la protection, utilisez l'outil Déverrouiller avec sa propre option --password.

Comment fonctionnent l'entrée et la sortie ?#

• Une entrée - lit l'entrée standard, une fois par exécution. -o - écrit le résultat sur la sortie standard.
• -o file.pdf écrit ce fichier. -o dir/ écrit dans un répertoire. Un répertoire qui n'existe pas encore exige la barre oblique finale, car un nom sans elle est écrit comme un fichier.
• Sans -o, les résultats vont dans le répertoire courant, sous le nom de fichier donné par le serveur.
• Dans un répertoire, pdfx ne remplace jamais un fichier existant ; il choisit un nouveau nom. Un -o file.pdf explicite remplace ce fichier.
• Un nom de fichier -o dont l'extension contredit le résultat, comme un ZIP issu de split enregistré en .pdf, est refusé avec le code de sortie 2 et code: output_mismatch. Rien n'est écrit.
• Une sortie impossible à écrire est une erreur d'usage détectée avant tout envoi.

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

Qu'affiche --json ?#

Pour un résultat enregistré, --json affiche le chemin, le type de contenu et la taille. Un outil qui renvoie un rapport affiche le rapport lui-même. Un lot affiche un seul rapport avec un statut par fichier.

{ "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 }
  ]
}

Un fichier en échec a error et reason à la place de path et bytes. Un outil de filtre sans correspondance affiche { "matched": false }. pdfx list --json affiche des lignes avec id, category, group, name, description, returns, files et filter.

Quelles options s'appliquent à tous les outils ?#

Quels sont les codes de sortie ?#

Les échecs affichent des lignes reason:, code: et hint: quand le serveur les fournit, afin qu'un script puisse se brancher sans comparer du texte. Un outil qui n'a rien à renvoyer, comme pdf-to-csv sur un PDF sans tableau, se termine avec 1 et code: no_content au lieu d'écrire un fichier vide. Les codes sont listés dans Codes d'erreur.

Comment pointer pdfx vers mon propre serveur ?#

Définissez PDFX_API_BASE, ou passez --api-base, avec l'adresse d'un pdfx-server auto-hébergé. Ajoutez PDFX_API_KEY si votre serveur exige une clé. Voir Auto-hébergement.

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

Comment appeler un point de terminaison que la CLI ne connaît pas ?#

pdfx call envoie une requête brute à un identifiant d'opération ou à un chemin /api/.... Utilisez --field name=value pour les champs de formulaire et --file field=path pour des fichiers supplémentaires. La commande n'envoie qu'une seule requête et ne valide rien en local : les mots de passe et les lots sont donc refusés.

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

Pages associées#

• Présentation pour développeurs avec l'API REST et l'authentification
• SDK TypeScript, la bibliothèque sur laquelle la ligne de commande est construite
• Serveurs MCP pour les agents IA
• L'article « pdfx CLI: One Catalog, Called From Your Terminal » du blog PDF123

FAQ#

pdfx fonctionne-t-il hors ligne ?#

Non. pdfx envoie chaque fichier à l'API PDF123 ou à votre propre serveur et enregistre le résultat en local : la base de l'API doit donc être joignable.

pdfx exige-t-il une clé d'API ?#

Non. L'usage anonyme fonctionne. Définissez PDFX_API_KEY ou passez --api-key si votre serveur en exige une. La clé est envoyée dans l'en-tête X-API-KEY.

Quelle version de Node pdfx exige-t-il ?#

Node 20.3 ou version ultérieure, ou Bun.

pdfx écrasera-t-il mes fichiers ?#

Pas lorsqu'il écrit dans un répertoire : un fichier existant n'est jamais remplacé. Si vous nommez vous-même le fichier de sortie avec -o file.pdf, ce fichier est remplacé ; choisissez donc un nouveau nom si vous voulez garder l'original.

Que se passe-t-il quand un outil de filtre ne trouve aucune correspondance ?#

Les outils de filtre, dont l'identifiant commence par filter-, laissent passer le fichier lorsque leur condition est remplie. Dans le cas contraire, pdfx affiche no match et se termine avec le code 0. Dans un lot, un tel fichier compte comme sans correspondance, et non comme en échec.