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

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 aidera à sélectionner un workspace et à trouver le template à éditer.

Vous pouvez aussi passer l’ID du template en second 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 ou si vous voulez utiliser un autre ID de template, vous pouvez le préciser avec l’option -t :

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

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 aidera à sélectionner un workspace et à trouver le snippet à éditer.

Vous pouvez aussi passer l’ID du snippet en second 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 fichier 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 fichier code.liquid du dossier courant et synchronisera automatiquement à 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 ou si vous voulez utiliser un autre ID de snippet, vous pouvez le préciser avec l’option -s :

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 trouvés jusqu’à deux niveaux 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 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. Si aucun workspace n’est indiqué dans un terminal interactif, le CLI vous demandera d’en choisir un.

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

Templates #

pdfmonkey template list                       # Dans tous les workspaces
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
pdfmonkey template create -w "Mon workspace" -n "Facture" --mode builder --folder 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, le dossier est lié au nouveau template : vous pouvez le surveiller avec watch immédiatement.

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 sont enregistrées en brouillon : utilisez publish pour les mettre en ligne.

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" [--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.

Documents #

pdfmonkey document list -w "Mon workspace"
pdfmonkey document list -t <template-id>,<template-id> -s failure --updated-since 2026-01-01
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é dans un chemin ou un dossier dès qu’il est prêt.

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 acceptent --json pour produire du JSON brut, par exemple pdfmonkey template list --json | jq '.[].id'.
Les commandes ne posent jamais de question quand toutes les options requises sont fournies. Hors d’un terminal, une information manquante provoque une erreur au lieu d’une question.
Les suppressions nécessitent -y ou --yes hors d’un terminal interactif.
Les erreurs sont affichées sur la sortie d’erreur standard et le processus se termine 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 à l’initialisation et 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.