CLI

This CLI tool is a great solution for developers who want to author PDFMonkey 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.

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:

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.

Command Structure #

Commands are organized by resource type:

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:

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)
• pdfmonkey watch: watch a template and its snippets together (see 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:

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.

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.

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

pdfmonkey template init <template-id> -e

Watch #

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

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:

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:

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.

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.

pdfmonkey template watch -p 2083 -l 2084

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

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:

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.

DIFF=delta PAGER=delta pdfmonkey template watch

Snippet Management #

Init #

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

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.

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.

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.

pdfmonkey snippet init <snippet-id> -e

Watch #

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

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:

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:

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

Init Multiple Resources #

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

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:

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:

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:

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.

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

Templates #

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.

Folders #

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 #

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 #

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 (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:

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