PDFMonkey 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

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.

Important

API Key in this README

The commands below will assume the API key is set in the 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 specify the template ID as a second argument.

pdfmonkey template init <template-id>

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

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

Tip

Open in Editor

You can also open the created directory in your default editor using the -e or --edit option.

pdfmonkey template init <template-id> -e

Watch

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

pdfmonkey template watch

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

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

pdfmonkey template watch <path>

If for some reason the directory doesn't contain metadata or you want to use a different template ID, you can specify it using the -t option:

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

Sometimes, it can be easier to debug the generated HTML instead of the PDF. You can do this by using the -D or --debug option.

pdfmonkey template watch -D -o

This will open the debug preview in your default browser.

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 specify the snippet ID as a second argument.

pdfmonkey snippet init <snippet-id>

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

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

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

Tip

Open in Editor

You can also open the created file in your default editor using the -e or --edit option.

pdfmonkey snippet init <snippet-id> -e

Watch

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

pdfmonkey snippet watch

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

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

pdfmonkey snippet watch <path>

If for some reason the directory doesn't contain metadata or you want to use a different snippet ID, you can specify it using the -s option:

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, --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 directory is a template or snippet directory, it is watched directly. Otherwise, you will be prompted to select the directories to watch among the ones found up to two levels below the current directory.

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 directory 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 options as the template watch command:

pdfmonkey watch -o -p 2083 -l 2084

Managing resources

Besides local edition, 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, --workspace option taking either the workspace ID or its name. You can also set the PDFMONKEY_WORKSPACE environment variable. When none is given in an interactive terminal, the CLI will ask you to pick one.

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

Templates

pdfmonkey template list                       # Across all workspaces
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
pdfmonkey template create -w "My Workspace" -n "Invoice" --mode builder --folder 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 directory (body.html.liquid, styles.scss and sample_data.json), the same layout used by init and watch. When creating a template, the directory is linked to the new template so you can watch it right away.

Like in the dashboard, changes are saved as a draft: use publish to make them live.

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

Documents

pdfmonkey document list -w "My Workspace"
pdfmonkey document list -t <template-id>,<template-id> -s failure --updated-since 2026-01-01
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, --output downloads the generated file to a path or directory once ready.

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 command accepts --json to output raw JSON, e.g. pdfmonkey template list --json | jq '.[].id'.
• Commands never prompt when all required options are given. Without a terminal, missing information is an error rather than a prompt.
• Deletions require -y, --yes when not run in an interactive terminal.
• Errors are printed on the standard error output and the process exits with a non-zero code.

Metadata

The CLI stores metadata in a .pdfmonkey.json file within each resource directory. This file contains the resource type and ID, allowing commands to run without explicitly specifying IDs. This metadata is automatically created when initializing resources and 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, --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.

License

This project is open-sourced under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for details.