mirror of
https://github.com/pdfme/pdfme.git
synced 2026-04-17 20:49:43 -04:00
128 lines
5.2 KiB
Markdown
128 lines
5.2 KiB
Markdown
# CLI
|
|
|
|
`@pdfme/cli` is the command-line surface for JSON-first pdfme workflows.
|
|
|
|
It is designed for:
|
|
|
|
- local template iteration without writing a custom Node script
|
|
- CI checks before running `generate`
|
|
- agentic workflows that need machine-readable output
|
|
- `basePdf` overlay work, where you place fields on top of an existing PDF
|
|
|
|
## Installation
|
|
|
|
Node.js 20 or later is required.
|
|
|
|
```bash
|
|
npm install -D @pdfme/cli
|
|
```
|
|
|
|
You can also run it directly with `npx`:
|
|
|
|
```bash
|
|
npx @pdfme/cli generate --help
|
|
```
|
|
|
|
## Main Commands
|
|
|
|
- `pdfme generate`
|
|
- generate a PDF from a template + inputs or a unified job file
|
|
- optionally render page images with `--image`
|
|
- optionally overlay a grid and schema bounds with `--grid`
|
|
- use `--verbose` to print input/output/render settings to stderr without polluting JSON stdout
|
|
- `pdfme validate`
|
|
- validate a template or unified job before generation
|
|
- use `--json` for machine-readable inspection output
|
|
- use `--verbose` to print source/mode/count summaries to stderr
|
|
- `pdfme doctor`
|
|
- diagnose runtime, font, `basePdf`, cache, and output-path issues before generation
|
|
- use `--verbose` to print target/input/runtime summaries to stderr
|
|
- `pdfme pdf2img`
|
|
- convert an existing PDF into page images
|
|
- use `--verbose` to print source/output/render settings to stderr without polluting JSON stdout
|
|
- `pdfme pdf2size`
|
|
- inspect page sizes in millimeters
|
|
- use `--verbose` to print source/total-page information to stderr
|
|
- `pdfme examples`
|
|
- export official example assets, optionally as a unified job with sample inputs
|
|
- use `--verbose` to print manifest/template source and output destination to stderr
|
|
|
|
## Typical Workflow
|
|
|
|
Start from an official example, inspect the runtime assumptions, then generate images for visual review:
|
|
|
|
```bash
|
|
pdfme examples invoice --withInputs -o job.json
|
|
pdfme doctor job.json --json
|
|
pdfme generate job.json -o out.pdf --image --grid
|
|
```
|
|
|
|
This is especially useful for agentic or CI workflows because the CLI can return structured JSON instead of human-only output.
|
|
|
|
## Existing PDF Overlay Workflow
|
|
|
|
If you already have a PDF and want to place text, dates, signatures, or other fields on top of it:
|
|
|
|
```bash
|
|
pdfme pdf2img invoice.pdf --grid --gridSize 10
|
|
pdfme pdf2size invoice.pdf --json
|
|
pdfme doctor template.json -o out.pdf --image --json
|
|
pdfme generate -t template.json -i inputs.json -o out.pdf --image --grid
|
|
```
|
|
|
|
In this flow, your template uses the existing PDF as `basePdf`, and pdfme renders only the overlay fields.
|
|
|
|
## Machine-Readable Contract
|
|
|
|
When you pass `--json`:
|
|
|
|
- stdout is JSON only
|
|
- success payloads include `command`
|
|
- `--verbose` writes supplementary context to stderr
|
|
- failures return `ok: false` with a structured error
|
|
- `doctor` returns `ok: true` when the command ran successfully, and uses `healthy` to report whether blocking issues were found
|
|
- scalar page counts use canonical names such as `pageCount`, `templatePageCount`, and `estimatedPageCount`
|
|
- per-page arrays stay under `pages`, with `pageNumber` as the page index field
|
|
- `validate --json` and `doctor --json` return field-level `inputHints`, so automation can tell whether a field expects a plain string, an asset-like string with `contentKind`, a barcode string with a human-readable `rule`, a `string[][]` table payload, a date/time string with `format` metadata, a constrained string enum, a group-aware enum, or a JSON string object
|
|
|
|
This makes the CLI suitable for automation, agents, and CI gates.
|
|
|
|
For example, image/signature/svg fields expose `contentKind`, barcode fields expose `contentKind` plus a human-readable `rule`, table fields expose `columnCount`, `columnHeaders`, and `acceptsJsonString`, date fields expose `format` and `canonicalFormat` and are validated against canonical stored content, `select` and `checkbox` expose enum-style `allowedValues`, `radioGroup` adds `groupName` and `groupMemberNames`, and `multiVariableText` exposes expected variable names and a sample JSON string payload.
|
|
|
|
## Font Contract
|
|
|
|
The CLI treats fonts as a source contract rather than a filename convention.
|
|
|
|
Supported inputs:
|
|
|
|
- local `.ttf` paths via `--font`
|
|
- local `.ttf` paths in unified job `options.font`
|
|
- public direct `http(s)` font asset URLs
|
|
- `.ttf` data URIs
|
|
- inline bytes from programmatic use
|
|
|
|
Current policy:
|
|
|
|
- direct `fonts.gstatic.com/...ttf` URLs are supported remote sources
|
|
- `fonts.googleapis.com/css*` stylesheet URLs are not supported
|
|
- unsafe/private/loopback font URLs are rejected
|
|
- `.otf` and `.ttc` are currently outside the supported contract
|
|
|
|
For CJK content, the CLI can automatically resolve and cache `NotoSansJP` unless you disable it with `--noAutoFont`.
|
|
|
|
## Remote Font Runtime Safety
|
|
|
|
Explicit remote fonts are resolved by the CLI before calling the generator.
|
|
|
|
- timeout: 15 seconds
|
|
- size limit: 32 MiB
|
|
- network/HTTP/timeout/size-limit failures are returned as `EFONT`
|
|
|
|
`pdfme doctor fonts ... --json` includes `needsNetwork` in each font source diagnosis so you can tell in advance whether the current job depends on network access.
|
|
|
|
## More Details
|
|
|
|
For the full command reference, examples, and current implementation notes, see the package README:
|
|
|
|
- [`packages/cli/README.md`](https://github.com/pdfme/pdfme/blob/main/packages/cli/README.md)
|