# CLI PDFMonkey : gérer vos modèles en ligne de commande


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.

```bash
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 :

```bash
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 :

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

> [!WARNING]
> **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 :

```bash
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 :

```bash
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](#initialiser-plusieurs-ressources))
- `pdfmonkey watch` : surveiller un template et ses snippets ensemble (voir [Surveiller plusieurs ressources](#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 :

```bash
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.

```bash
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.

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

> [!TIP]
> **Ouvrir dans l’éditeur**
>
> Vous pouvez également ouvrir le dossier créé dans votre éditeur par défaut en utilisant l’option `-e` ou `--edit`.
> 
> ```bash
> pdfmonkey template init <template-id> -e
> ```


### Watch

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

```bash
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 :

```bash
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 :

```bash
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`.

```bash
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`.

```bash
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.

```bash
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 :

```bash
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 :

1. Écraser les fichiers locaux avec les données du template.
2. Garder les fichiers locaux et remplacer les données du template lors de la prochaine synchronisation.
3. 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.

```bash
DIFF=delta PAGER=delta pdfmonkey template watch
```

## Gestion des snippets

### Init

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

```bash
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.

```bash
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.

```bash
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`.

> [!TIP]
> **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`.
> 
> ```bash
> pdfmonkey snippet init <snippet-id> -e
> ```


### Watch

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

```bash
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 :

```bash
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 :

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

## Initialiser plusieurs ressources

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

```bash
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 :

```bash
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 :

```bash
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` :

```bash
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.

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

### Templates

```bash
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`).

> [!NOTE]
> **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

```bash
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

```bash
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

```bash
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](../generation-de-documents/statuts-des-documents.md) (`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 :

```json
{
  "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.
