Cet outil CLI est une excellente solution pour les développeurs qui souhaitent créer des templates PDFMonkey en utilisant leur propre éditeur de code et leur environnement de développement local.

Il permet aussi de gérer vos workspaces, templates, dossiers, snippets et documents depuis le terminal, depuis un script ou depuis un agent IA.

Installation #

Le CLI PDFMonkey nécessite Node.js 22.12 ou plus récent et s’installe via npm.

npm install -g @pdfmonkey/cli

Une fois installé, la commande pdfmonkey sera disponible dans votre terminal.

Aide #

Pour obtenir la liste des commandes disponibles et l’aide générale, exécutez la commande suivante :

pdfmonkey help

Pour vérifier la version installée, exécutez pdfmonkey --version.

Authentification #

Il existe deux façons de s’authentifier avec le CLI PDFMonkey :

Toutes les commandes acceptent l’option -k ou --api-key pour spécifier une clé API.
Vous pouvez également définir la variable d’environnement PDFMONKEY_API_KEY.

Clé API dans cette page

Les commandes ci-dessous supposent que la clé API est définie dans la variable d’environnement.

Structure des commandes #

Les commandes sont organisées par type de ressource :

pdfmonkey <ressource> <commande> [options]

Ressources disponibles :

workspace ou ws : lister les workspaces PDFMonkey
template ou tpl : gérer les templates PDFMonkey
folder ou fld : gérer les dossiers de templates PDFMonkey
snippet ou snp : gérer les snippets PDFMonkey
document ou doc : gérer les documents PDFMonkey

Par exemple :

pdfmonkey template init <template-id>
# ou avec l’alias raccourci
pdfmonkey tpl init <template-id>

Les commandes courantes ont aussi des alias courts : list → ls, get → show, delete → rm et, pour les documents, create → generate.

Quelques commandes se trouvent au premier niveau :

pdfmonkey init : initialiser plusieurs templates et snippets à la suite (voir Initialiser plusieurs ressources)
pdfmonkey watch : surveiller un template et ses snippets ensemble (voir Surveiller plusieurs ressources)
pdfmonkey whoami : afficher le compte auquel appartient la clé API

Gestion des templates #

Init #

Pour commencer à éditer un template PDFMonkey, exécutez la commande suivante :

pdfmonkey template init

La commande vous guide pour sélectionner un workspace et trouver le template à éditer.

Vous pouvez aussi passer l’ID du template en argument.

pdfmonkey template init <template-id>

Vous serez ensuite invité à choisir le dossier de destination des fichiers du template. Vous pouvez également le spécifier en second argument.

pdfmonkey template init <template-id> <dossier-destination>

Ouvrir dans l’éditeur

Vous pouvez également ouvrir le dossier créé dans votre éditeur par défaut en utilisant l’option -e ou --edit.

pdfmonkey template init <template-id> -e

Watch #

Pour surveiller un dossier de template et synchroniser les modifications vers PDFMonkey, exécutez la commande suivante :

pdfmonkey template watch

Cela commencera à surveiller les fichiers dans le dossier courant et synchronisera automatiquement les modifications. Le CLI utilise les métadonnées du fichier .pdfmonkey.json pour identifier le template.

Pour surveiller un dossier différent, passez simplement le chemin comme premier argument :

pdfmonkey template watch <chemin>

Si le dossier ne contient pas de métadonnées, son nom est utilisé comme ID du template. Vous pouvez en préciser un autre avec l’option -t, ignorée quand le dossier a déjà des métadonnées :

pdfmonkey template watch [chemin] -t <template-id>

Aperçu #

La commande watch démarrera un serveur local pour prévisualiser le template. L’aperçu se rafraîchira automatiquement lorsque les modifications seront synchronisées.

Vous pouvez ouvrir l’aperçu lorsque le serveur est en cours d’exécution en utilisant l’option -o ou --open-browser.

pdfmonkey template watch -o

Par défaut, le serveur d’aperçu fonctionne sur le port 2081 et le serveur de rechargement automatique sur le port 2082. Vous pouvez spécifier des ports différents en utilisant les options -p/--port et -l/--livereload-port.

pdfmonkey template watch -p 2083 -l 2084

Vous pouvez également définir les variables d’environnement PORT et LIVE_RELOAD_PORT pour personnaliser les ports.

PORT=2083 LIVE_RELOAD_PORT=2084 pdfmonkey template watch

Aperçu de débogage #

Il est parfois plus simple de déboguer le HTML généré que le PDF. Utilisez l’option -D ou --debug pour prévisualiser le HTML à la place :

pdfmonkey template watch -D -o

Gestion des conflits #

Au lancement de la commande watch, le CLI vérifiera s’il y a des conflits entre les fichiers locaux et les données du template. S’il y en a, vous serez invité à choisir entre :

Écraser les fichiers locaux avec les données du template.
Garder les fichiers locaux et remplacer les données du template lors de la prochaine synchronisation.
Voir un diff des modifications.

Par défaut, l’outil de diff utilisé est diff -u et le patch est affiché avec le pager less. Vous pouvez spécifier un outil de diff et un pager différents en utilisant les variables d’environnement DIFF et PAGER, respectivement.

DIFF=delta PAGER=delta pdfmonkey template watch

Gestion des snippets #

Init #

Pour commencer à éditer un snippet PDFMonkey, exécutez la commande suivante :

pdfmonkey snippet init

La commande vous guide pour sélectionner un workspace et trouver le snippet à éditer.

Vous pouvez aussi passer l’ID du snippet en argument.

pdfmonkey snippet init <snippet-id>

Vous serez ensuite invité à choisir le dossier de destination du snippet. Vous pouvez également le spécifier en second argument.

pdfmonkey snippet init <snippet-id> <dossier-destination>

Le snippet est stocké dans un dossier organisé comme celui d’un template, avec son code dans un fichier nommé code.liquid.

Ouvrir dans l’éditeur

Vous pouvez également ouvrir le dossier du snippet créé dans votre éditeur par défaut en utilisant l’option -e ou --edit.

pdfmonkey snippet init <snippet-id> -e

Watch #

Pour surveiller un dossier de snippet et synchroniser les modifications vers PDFMonkey, exécutez la commande suivante :

pdfmonkey snippet watch

Cela commencera à surveiller le dossier courant et synchronisera automatiquement son fichier code.liquid à chaque modification. Le CLI utilise les métadonnées du fichier .pdfmonkey.json pour identifier le snippet.

Pour surveiller un dossier différent, passez simplement le chemin comme premier argument :

pdfmonkey snippet watch <chemin>

Si le dossier ne contient pas de métadonnées, son nom est utilisé comme ID du snippet. Vous pouvez en préciser un autre avec l’option -s, ignorée quand le dossier a déjà des métadonnées :

pdfmonkey snippet watch [chemin] -s <snippet-id>

Initialiser plusieurs ressources #

Pour initialiser plusieurs templates et snippets l’un après l’autre, exécutez :

pdfmonkey init

Pour chaque ressource, le CLI vous demande s’il s’agit d’un template ou d’un snippet, puis vous guide à travers les mêmes étapes que template init et snippet init. L’option -e ou --edit ouvre chaque ressource initialisée dans votre éditeur.

Surveiller plusieurs ressources #

Le CLI permet de surveiller plusieurs ressources (un template et plusieurs snippets) avec une seule commande :

pdfmonkey watch

Si le dossier courant est un dossier de template ou de snippet, il est surveillé directement. Sinon, vous serez invité à sélectionner les dossiers à surveiller parmi ceux situés jusqu’à deux niveaux de profondeur sous le dossier courant.

Vous pouvez aussi passer directement plusieurs chemins :

pdfmonkey watch chemin/vers/template chemin/vers/snippet

Le CLI détecte automatiquement si chaque dossier contient un template ou un snippet grâce aux métadonnées. Un seul template peut être surveillé à la fois, mais vous pouvez surveiller plusieurs snippets en parallèle.

Cette commande accepte les mêmes options d’aperçu que template watch :

pdfmonkey watch -o -p 2083 -l 2084

Gestion des ressources #

En plus de l’édition locale, le CLI couvre les opérations courantes sur vos ressources PDFMonkey. Chaque commande dispose d’une option --help qui liste toutes ses options.

Workspaces #

Les commandes qui agissent dans un workspace acceptent l’option -w ou --workspace, avec l’ID ou le nom du workspace. Vous pouvez aussi définir la variable d’environnement PDFMONKEY_WORKSPACE. Quand une commande a besoin d’un workspace et qu’aucun n’est indiqué, le CLI vous demande d’en choisir un dans un terminal interactif (ou utilise directement le vôtre si vous n’en avez qu’un). template list et document list couvrent alors tous les workspaces.

pdfmonkey whoami          # Vérifie à quel compte appartient la clé API
pdfmonkey workspace list

Templates #

pdfmonkey template list                       # Dans tous les workspaces, sauf si PDFMONKEY_WORKSPACE est défini
pdfmonkey template list -w "Mon workspace"    # Dans un workspace
pdfmonkey template list -w "Mon workspace" -f Factures   # Dans un dossier (ID ou nom), ou "none"
pdfmonkey template get <template-id>          # --json pour obtenir le contenu complet

pdfmonkey template create -w "Mon workspace" -n "Facture" --from ./facture   # Mode code par défaut
pdfmonkey template create -w "Mon workspace" -n "Facture" -m builder -f Factures
pdfmonkey template create -w "Mon workspace" -n "Badge" --output-type image --engine v5
pdfmonkey template update <template-id> --from ./facture
pdfmonkey template update <template-id> -n "Nouveau nom" --folder none
pdfmonkey template publish <template-id>
pdfmonkey template delete <template-id>

--from lit le contenu d’un dossier de template local (body.html.liquid, styles.scss et sample_data.json), avec la même organisation que pour init et watch. À la création d’un template, un dossier sans métadonnées est lié au nouveau template : vous pouvez le surveiller avec watch immédiatement. Un dossier qui a déjà des métadonnées reste lié à son template d’origine.

create et update acceptent aussi les options --output-type (pdf ou image) et --engine (par exemple v5).

Brouillons et publication

Comme dans le tableau de bord, les modifications du contenu (--from) et du moteur sont enregistrées en brouillon : utilisez publish pour les mettre en ligne. Les changements de nom, de dossier et de type de sortie s’appliquent immédiatement.

Dossiers #

pdfmonkey folder list -w "Mon workspace"
pdfmonkey folder create -w "Mon workspace" -n "Factures"
pdfmonkey folder rename <folder-id> "Devis"
pdfmonkey folder delete <folder-id>

Snippets #

pdfmonkey snippet list -w "Mon workspace"
pdfmonkey snippet list -w "Mon workspace" --search header
pdfmonkey snippet get <snippet-id>
pdfmonkey snippet create -w "Mon workspace" -n "header" --from ./header
pdfmonkey snippet update <snippet-id> --from ./header
pdfmonkey snippet delete <snippet-id>

--from lit le code du fichier code.liquid d’un dossier de snippet local. À la création d’un snippet, un dossier sans métadonnées est lié au nouveau snippet : vous pouvez le surveiller avec watch immédiatement.

Documents #

pdfmonkey document list -w "Mon workspace"
pdfmonkey document list -t <template-id>,<template-id> -s failure --updated-since 2026-01-01   # ISO 8601 ou timestamp UNIX
pdfmonkey document list -q facture-42 --page 2
pdfmonkey document get <document-id>          # --json pour obtenir le payload et les logs de génération

pdfmonkey document create -t <template-id> --payload @data.json -o ./factures/
pdfmonkey document create -t <template-id> --payload '{"name": "Alice"}' --meta '{"_filename": "alice.pdf"}' --wait
cat data.json | pdfmonkey document create -t <template-id> --payload - --draft
pdfmonkey document update <document-id> --payload @data.json --generate --wait
pdfmonkey document download <document-id> [chemin]
pdfmonkey document delete <document-id>

--payload et --meta acceptent du JSON en ligne, un fichier (@chemin/vers/fichier.json) ou l’entrée standard (-). Les documents sont générés immédiatement, sauf avec --draft. -o ou --output télécharge le fichier généré dès qu’il est prêt, dans un dossier existant ou vers un chemin de fichier.

Les filtres disponibles pour document list sont le ou les templates, le statut (draft, pending, generating, success ou failure), une recherche sur le nom de fichier ou l’ID, et la date de dernière modification.

Scripts et agents IA #

Le CLI est conçu pour être utilisé par des scripts et des agents IA autant que par des humains :

Toutes les commandes de gestion (list, get, create, update, delete…) acceptent --json pour produire du JSON brut, par exemple pdfmonkey template list --json | jq '.[].id'. Les listes sont des tableaux, sauf document list qui renvoie { "items": […], "meta": {…} } (utilisez jq '.items[].id').
Les commandes de gestion ne posent jamais de question quand toutes les options requises sont fournies, sauf les suppressions qui demandent une confirmation en l’absence de -y. Hors d’un terminal, une information manquante provoque une erreur au lieu d’une question. init et watch sont interactives et destinées aux humains.
Les suppressions nécessitent -y ou --yes hors d’un terminal interactif.
Les commandes de gestion affichent les erreurs sur la sortie d’erreur standard et se terminent avec un code non nul.

Métadonnées #

Le CLI stocke des métadonnées dans un fichier .pdfmonkey.json à l’intérieur de chaque dossier de ressource. Ce fichier contient le type et l’ID de la ressource, ce qui permet de lancer les commandes sans préciser d’ID. Il est créé automatiquement par init, par create --from et par watch quand le nom du dossier ou l’option -t/-s fournit un ID valide. Il est utilisé par les commandes watch.

Le fichier .pdfmonkey.json ressemble à ceci :

{
  "type": "template",
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Configuration #

Voici un résumé des variables d’environnement qui peuvent être définies pour personnaliser le comportement du CLI :

PDFMONKEY_API_KEY : la clé API à utiliser pour l’authentification.
PDFMONKEY_WORKSPACE : le workspace par défaut (ID ou nom).
PDFMONKEY_API_BASE : l’URL de base de l’API (par défaut : https://api.pdfmonkey.io/api/v1).
EDITOR : l’éditeur ouvert par l’option -e ou --edit des commandes init.
DIFF : l’outil de diff à utiliser.
PAGER : le pager à utiliser pour afficher les diffs.
PORT : le port sur lequel exécuter le serveur d’aperçu.
LIVE_RELOAD_PORT : le port sur lequel exécuter le serveur de rechargement automatique.