# PDFMonkey CLI: Manage Templates From the Terminal


This CLI tool is a great solution for developers who want to author [PDFMonkey](https://pdfmonkey.io) templates using their own code editor and local development environment.

It also lets you manage your workspaces, templates, folders, snippets and documents from the terminal, from scripts or from an AI agent.

## Installation

The PDFMonkey CLI requires Node.js 22.12 or later and can be installed using npm.

```bash
npm install -g @pdfmonkey/cli
```

Once installed, the `pdfmonkey` command will be available in your terminal.

## Help

To get a list of available commands and general help, run the following command:

```bash
pdfmonkey help
```

To check which version is installed, run `pdfmonkey --version`.

## Authentication

There are two ways to authenticate with the PDFMonkey CLI:

1. All commands accept the `-k` or `--api-key` option to specify an API key.
2. You can also set the `PDFMONKEY_API_KEY` environment variable.

> [!WARNING]
> **API Key in this page**
>
> The commands below will **assume the API key is set in the environment variable.**


## Command Structure

Commands are organized by resource type:

```bash
pdfmonkey <resource> <command> [options]
```

Currently supported resources:

- `workspace` or `ws`: List PDFMonkey workspaces
- `template` or `tpl`: Manage PDFMonkey templates
- `folder` or `fld`: Manage PDFMonkey template folders
- `snippet` or `snp`: Manage PDFMonkey snippets
- `document` or `doc`: Manage PDFMonkey documents

For example:

```bash
pdfmonkey template init <template-id>
# or using the shorthand alias
pdfmonkey tpl init <template-id>
```

Common commands also have short aliases: `list` → `ls`, `get` → `show`, `delete` → `rm` and, for documents, `create` → `generate`.

A few commands live at the top level:

- `pdfmonkey init`: initialize several templates and snippets in a row (see [Init Multiple Resources](#init-multiple-resources))
- `pdfmonkey watch`: watch a template and its snippets together (see [Watch Multiple Resources](#watch-multiple-resources))
- `pdfmonkey whoami`: show the account the API key belongs to

## Template Management

### Init

To start editing a PDFMonkey template, run the following command:

```bash
pdfmonkey template init
```

The command will help you select a workspace and find the template you want to edit.

Alternatively, you can pass the template ID as an argument.

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

You will then be prompted to choose the destination folder for the template files. You can also specify the destination folder as a second argument.

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

> [!TIP]
> **Open in Editor**
>
> You can also open the created folder in your default editor using the `-e` or `--edit` option.
> 
> ```bash
> pdfmonkey template init <template-id> -e
> ```


### Watch

To start watching a template folder and sync the changes to PDFMonkey, run the following command:

```bash
pdfmonkey template watch
```

This will start watching files in **the current folder** and sync automatically. The CLI uses the metadata stored in the `.pdfmonkey.json` file to identify the template.

To monitor a different folder, simply pass the path as the first argument:

```bash
pdfmonkey template watch <path>
```

If the folder doesn’t contain metadata, its name is used as the template ID. You can specify another one using the `-t` option, which is ignored when the folder already has metadata:

```bash
pdfmonkey template watch [path] -t <template-id>
```

### Preview

The `watch` command will start a local server to preview the template. The preview will automatically refresh when changes are synced.

You can open the preview when the server is running using the `-o` or `--open-browser` option.

```bash
pdfmonkey template watch -o
```

By default, the preview server runs on port 2081 and the live-reload server runs on port 2082. You can specify different ports using the `-p/--port` and `-l/--livereload-port` options.

```bash
pdfmonkey template watch -p 2083 -l 2084
```

Alternatively, you can set the `PORT` and `LIVE_RELOAD_PORT` environment variables to customize the ports.

```bash
PORT=2083 LIVE_RELOAD_PORT=2084 pdfmonkey template watch
```

### Debug preview

It can be easier to debug the generated HTML than the PDF. Use the `-D` or `--debug` option to preview the HTML instead:

```bash
pdfmonkey template watch -D -o
```

### Dealing with conflicts

When starting the `watch` command, the CLI will check if there are any conflicts between the local files and the template data. If there are, you will be prompted to choose between:

1. Overwrite the local files with the template data.
2. Keep the local files and override the template data on the next sync.
3. To see a diff of the changes.

By default, the diff tool used is `diff -u` and the patch is displayed with the `less` pager. You can specify different diff-tool and pager using the `DIFF` and `PAGER` environment variables, respectively.

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

## Snippet Management

### Init

To start editing a PDFMonkey snippet, run the following command:

```bash
pdfmonkey snippet init
```

The command will help you select a workspace and find the snippet you want to edit.

Alternatively, you can pass the snippet ID as an argument.

```bash
pdfmonkey snippet init <snippet-id>
```

You will then be prompted to choose the destination folder for the snippet. You can also specify the destination folder as a second argument.

```bash
pdfmonkey snippet init <snippet-id> <destination-folder>
```

The snippet will be stored in a folder structure similar to templates, with the code in a file named `code.liquid`.

> [!TIP]
> **Open in Editor**
>
> You can also open the created snippet folder in your default editor using the `-e` or `--edit` option.
> 
> ```bash
> pdfmonkey snippet init <snippet-id> -e
> ```


### Watch

To start watching a snippet folder and sync the changes to PDFMonkey, run the following command:

```bash
pdfmonkey snippet watch
```

This will start watching the **current folder** and sync its `code.liquid` file automatically when changes are detected. The CLI uses the metadata stored in the `.pdfmonkey.json` file to identify the snippet.

To monitor a different folder, simply pass the path as the first argument:

```bash
pdfmonkey snippet watch <path>
```

If the folder doesn’t contain metadata, its name is used as the snippet ID. You can specify another one using the `-s` option, which is ignored when the folder already has metadata:

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

## Init Multiple Resources

To initialize several templates and snippets one after the other, run:

```bash
pdfmonkey init
```

For each resource, you will be asked whether it’s a template or a snippet, then guided through the same steps as `template init` and `snippet init`. The `-e` or `--edit` option opens each initialized resource in your editor.

## Watch Multiple Resources

The CLI allows you to watch multiple resources (one template and multiple snippets) simultaneously with a single command:

```bash
pdfmonkey watch
```

If the current folder is a template or snippet folder, it is watched directly. Otherwise, you will be prompted to select the folders to watch among the ones located up to two levels deep below the current folder.

You can also directly specify multiple paths:

```bash
pdfmonkey watch path/to/template path/to/snippet
```

When watching multiple resources, the command will automatically detect if each folder contains a template or a snippet based on the metadata. Note that **only one template can be watched at a time**, but you can watch multiple snippets alongside it.

This combined watch command supports the same preview options as the `template watch` command:

```bash
pdfmonkey watch -o -p 2083 -l 2084
```

## Managing Resources

Besides local editing, the CLI covers the everyday operations on your PDFMonkey resources. Every command has a `--help` option listing all its options.

### Workspaces

Commands that work within a workspace accept a `-w` or `--workspace` option taking either the workspace ID or its name. You can also set the `PDFMONKEY_WORKSPACE` environment variable. When a command needs a workspace and none is given, the CLI asks you to pick one in an interactive terminal (or uses yours directly if you only have one). `template list` and `document list` cover all workspaces instead.

```bash
pdfmonkey whoami          # Check which account the API key belongs to
pdfmonkey workspace list
```

### Templates

```bash
pdfmonkey template list                       # Across all workspaces, unless PDFMONKEY_WORKSPACE is set
pdfmonkey template list -w "My Workspace"     # In a workspace
pdfmonkey template list -w "My Workspace" -f Invoices   # In a folder (ID or name), or "none"
pdfmonkey template get <template-id>          # Use --json to get the full content

pdfmonkey template create -w "My Workspace" -n "Invoice" --from ./invoice   # Code mode by default
pdfmonkey template create -w "My Workspace" -n "Invoice" -m builder -f Invoices
pdfmonkey template create -w "My Workspace" -n "Badge" --output-type image --engine v5
pdfmonkey template update <template-id> --from ./invoice
pdfmonkey template update <template-id> -n "New name" --folder none
pdfmonkey template publish <template-id>
pdfmonkey template delete <template-id>
```

`--from` reads the content from a local template folder (`body.html.liquid`, `styles.scss` and `sample_data.json`), the same layout used by `init` and `watch`. When creating a template, a folder without metadata is linked to the new template so you can `watch` it right away. A folder that already has metadata stays linked to its original template.

`create` and `update` also accept `--output-type` (`pdf` or `image`) and `--engine` (e.g. `v5`) options.

> [!NOTE]
> **Drafts and publishing**
>
> Like in the dashboard, content (`--from`) and engine changes are saved as a draft: use `publish` to make them live. Name, folder and output type changes apply immediately.


### Folders

```bash
pdfmonkey folder list -w "My Workspace"
pdfmonkey folder create -w "My Workspace" -n "Invoices"
pdfmonkey folder rename <folder-id> "Quotes"
pdfmonkey folder delete <folder-id>
```

### Snippets

```bash
pdfmonkey snippet list -w "My Workspace"
pdfmonkey snippet list -w "My Workspace" --search header
pdfmonkey snippet get <snippet-id>
pdfmonkey snippet create -w "My Workspace" -n "header" --from ./header
pdfmonkey snippet update <snippet-id> --from ./header
pdfmonkey snippet delete <snippet-id>
```

`--from` reads the code from the `code.liquid` file of a local snippet folder. When creating a snippet, a folder without metadata is linked to the new snippet so you can `watch` it right away.

### Documents

```bash
pdfmonkey document list -w "My Workspace"
pdfmonkey document list -t <template-id>,<template-id> -s failure --updated-since 2026-01-01   # ISO 8601 or UNIX timestamp
pdfmonkey document list -q invoice-42 --page 2
pdfmonkey document get <document-id>          # Use --json to get the payload and generation logs

pdfmonkey document create -t <template-id> --payload @data.json -o ./invoices/
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> [path]
pdfmonkey document delete <document-id>
```

`--payload` and `--meta` accept inline JSON, a file (`@path/to/file.json`) or the standard input (`-`). Documents are generated right away unless `--draft` is given. `-o` or `--output` downloads the generated file once ready, into an existing folder or to a file path.

The available filters for `document list` are the template(s), the [status](../generating-documents/document-statuses.md) (`draft`, `pending`, `generating`, `success` or `failure`), a search on the filename or ID, and the last update date.

## Scripting and AI Agents

The CLI is designed to be used by scripts and LLM-based agents as well as humans:

- Every management command (`list`, `get`, `create`, `update`, `delete`…) accepts `--json` to output raw JSON, e.g. `pdfmonkey template list --json | jq '.[].id'`. Lists are arrays, except `document list` which returns `{ "items": […], "meta": {…} }` (use `jq '.items[].id'`).
- Management commands never prompt when all required options are given, except deletions which ask for confirmation unless `-y` is given. Without a terminal, missing information is an error rather than a prompt. `init` and `watch` are interactive and meant for humans.
- Deletions require `-y` or `--yes` when not run in an interactive terminal.
- Management commands print errors on the standard error output and exit with a non-zero code.

## Metadata

The CLI stores metadata in a `.pdfmonkey.json` file within each resource folder. This file contains the resource type and ID, allowing commands to run without explicitly specifying IDs. This metadata is automatically created by `init`, by `create --from` and by `watch` when the folder name or the `-t`/`-s` option gives a valid ID. It is used by the watch commands.

The `.pdfmonkey.json` file looks like this:

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

## Configuration

Here is a summary of the environment variables that can be set to customize the behavior of the CLI:

- `PDFMONKEY_API_KEY`: The API key to use for authentication.
- `PDFMONKEY_WORKSPACE`: The default workspace (ID or name).
- `PDFMONKEY_API_BASE`: The base URL of the API (default: `https://api.pdfmonkey.io/api/v1`).
- `EDITOR`: The editor opened by the `-e` or `--edit` option of `init` commands.
- `DIFF`: The diff tool to use.
- `PAGER`: The pager to use when displaying diffs.
- `PORT`: The port to run the preview server on.
- `LIVE_RELOAD_PORT`: The port to run the live-reload server on.
