CLI

@pdfme/cli は、JSON-first な pdfme workflow のためのコマンドラインインターフェースです。

主な用途:

custom Node script を書かずに template と inputs から PDF を生成する
generate の前に template や unified job を検証する
CI や agent 実行前に runtime、font、basePdf、出力先の問題を診断する
既存 PDF を画像やページサイズ情報に変換する
official example を template または unified job として取り出す

インストール

Node.js 20 以降が必要です。

npm install -D @pdfme/cli

npx から直接実行することもできます。

npx @pdfme/cli generate --help

コマンド一覧

pdfme generate
- unified job または --template + --inputs から PDF を生成する
- 必要に応じてページ画像も出力する
- 画像にグリッド線と schema 境界を重ねられる
pdfme validate
- 生成前に template または unified job を検証する
- --json で machine-readable な inspection を返す
pdfme doctor
- 環境、input、font、basePdf、cache、output path を診断する
pdfme pdf2img
- 既存 PDF をページ画像へ変換する
pdfme pdf2size
- PDF のページサイズをミリメートル単位で確認する
pdfme examples
- official example を一覧表示または出力する

`pdfme generate`

generate は次の 2 形式を受け付けます。

unified job file
template file + separate inputs file

使用例:

# Unified job file: { template, inputs, options? }
pdfme generate job.json -o out.pdf

# Template + inputs を別ファイルで指定
pdfme generate -t template.json -i inputs.json -o out.pdf

# ページ画像も出力
pdfme generate job.json -o out.pdf --image

# 画像にグリッド線と schema 境界を重ねる
pdfme generate job.json -o out.pdf --grid

# CLI から basePdf を上書き
pdfme generate -t template.json -i inputs.json --basePdf invoice.pdf -o out.pdf

# CI / agent 向けの構造化出力
pdfme generate job.json -o out.pdf --image --json

主なオプション:

オプション	デフォルト	説明
`[file]`	-	`{ template, inputs, options? }` を含む unified job file
`-t, --template`	-	Template JSON file
`-i, --inputs`	-	Input JSON file
`-o, --output`	`output.pdf`	出力 PDF パス
`--force`	`false`	暗黙の `output.pdf` 上書きを許可する
`--image`	`false`	生成した各ページの画像も書き出す
`--imageFormat`	`png`	`png` または `jpeg`
`--scale`	`1`	画像レンダリングの scale
`--grid`	`false`	生成画像にグリッド線と schema 境界を描画する
`--gridSize`	`10`	グリッド間隔(mm)
`--font`	-	`Name=path.ttf` 形式のローカル custom font。複数指定時はカンマ区切り
`--basePdf`	-	`template.basePdf` を PDF file path で上書きする
`--noAutoFont`	`false`	CJK 文字向けの `NotoSansJP` 自動解決を無効化する
`-v, --verbose`	`false`	入出力や描画条件を stderr に出す
`--json`	`false`	stdout に JSON のみを出す

注意点:

output.pdf が既に存在し、かつ -o や --force を明示していない場合、generate は上書きを拒否します。
--grid は --image を付けていなくても画像出力を有効にします。
生成画像は出力 PDF と同じディレクトリに <output-base>-1.png, <output-base>-2.png の形式で保存されます。--imageFormat jpeg の場合は .jpg になります。
--font のローカルパスは CLI 実行時の current working directory 基準で解決されます。
unified job の options.font.<name>.data にあるローカルパスは、job file または template file のあるディレクトリ基準で解決されます。
CJK が含まれ、かつ明示的な font source がない場合、CLI は --noAutoFont が付いていない限り NotoSansJP を自動解決して cache します。

Unified job の例:

{
  "template": {
    "basePdf": {
      "width": 210,
      "height": 297,
      "padding": [20, 20, 20, 20]
    },
    "schemas": [
      [
        {
          "name": "customerName",
          "type": "text",
          "position": { "x": 20, "y": 50 },
          "width": 80,
          "height": 10
        }
      ]
    ]
  },
  "inputs": [
    { "customerName": "John Doe" }
  ],
  "options": {
    "font": {
      "NotoSansJP": {
        "data": "https://fonts.gstatic.com/...",
        "fallback": false,
        "subset": true
      }
    }
  }
}

template.basePdf には "./invoice.pdf" のような相対 PDF path も指定できます。必要なら --basePdf で実行時に上書きできます。

--json 指定時の stdout は JSON のみになります。

{
  "ok": true,
  "command": "generate",
  "mode": "job",
  "templatePageCount": 1,
  "inputCount": 1,
  "pageCount": 1,
  "outputPath": "out.pdf",
  "outputBytes": 12345,
  "imagePaths": ["out-1.png"]
}

`pdfme validate`

validate は template file または unified job file を、生成前に検証します。

使用例:

pdfme validate template.json
pdfme validate job.json --json
cat job.json | pdfme validate - --json
pdfme validate template.json --strict
pdfme validate template.json -v --json

主な検証内容:

pdfme の template validation による構造チェック
未知の schema type
同一ページ内の重複 field name
ページをまたいだ同名 field の warning
ページ境界外にはみ出す field position の warning
template top-level の未知フィールドに対する warning
unified job が generate に渡せる形かどうか
unified job に対する field-level input contract check

便利なフラグ:

--strict
- warning も failure 扱いにする
--json
- valid, errors, warnings, inspection, inputHints を返す
-v, --verbose
- 入力 source、mode、件数、サマリを stderr に出す

inputHints により、generate 実行前に writable field が何を期待しているかを判定できます。現行 CLI は次の入力種別を区別します。

plain string
contentKind 付きの asset-like string
human-readable な rule を持つ barcode string
string[][] の table payload
format metadata を持つ canonical date/time string
select / checkbox / radioGroup の constrained enum string
multiVariableText 向けの JSON string object

`pdfme doctor`

doctor は実行環境や特定の template/job を、生成前に診断します。

使用例:

# 環境診断
pdfme doctor

# Template または job の診断
pdfme doctor job.json --json

# stdin から診断
cat job.json | pdfme doctor - --json

# Font に絞った診断
pdfme doctor fonts job.json --json

# 自動 CJK font 解決を無効化した条件で診断
pdfme doctor job.json --noAutoFont --json

# generate と同じ output path / image output 条件で事前診断
pdfme doctor job.json -o artifacts/out.pdf --image --imageFormat jpeg --json

`pdfme pdf2img`

既存 PDF をページ画像に変換します。

使用例:

pdfme pdf2img invoice.pdf
pdfme pdf2img invoice.pdf --grid --gridSize 10
pdfme pdf2img invoice.pdf --pages 1-3
pdfme pdf2img invoice.pdf -o ./images --imageFormat jpeg
pdfme pdf2img invoice.pdf -o ./images --json

挙動:

-o, --output はファイル名ではなくディレクトリを受け取ります
出力ファイル名は <input-base>-<page>.png または .jpg です
--pages は 1-3 や 1,3,5 のような形式を受け取ります
--grid はレンダリングされたページ画像にミリメートルグリッドを描画します
--json では pageCount, selectedPageCount, outputPaths, 各ページの width/height を返します

`pdfme pdf2size`

PDF のページサイズをミリメートル単位で確認します。

使用例:

pdfme pdf2size invoice.pdf
pdfme pdf2size invoice.pdf --json

標準サイズを検出できる場合、人間向け出力には A4 portrait のようなラベルも付きます。JSON 出力の例:

{
  "ok": true,
  "command": "pdf2size",
  "pageCount": 1,
  "pages": [
    { "pageNumber": 1, "width": 210, "height": 297 }
  ]
}

`pdfme examples`

playground の asset manifest から official example を一覧表示または出力します。

使用例:

# 一覧表示
pdfme examples --list

# name 未指定でも一覧表示
pdfme examples

# Template を stdout に出力
pdfme examples invoice

# Template をファイルに保存
pdfme examples invoice -o template.json

# サンプル入力付き unified job を出力
pdfme examples invoice --withInputs -o job.json

# Manifest metadata を JSON で取得
pdfme examples --list --json

挙動:

manifest と template asset は https://playground.pdfme.com/template-assets から取得されます
PDFME_EXAMPLES_BASE_URL 環境変数で base URL を上書きできます
--withInputs では sample inputs に加えて、official hosted font が必要な例では options.font も同梱されます
--json の list mode では template name、schema type、font name、page count などの metadata を返します

Font Contract

CLI は font を「明示的な source contract」として扱います。

サポートされる explicit font source:

--font Name=./path.ttf による local .ttf file
unified job options.font.<name>.data にある local .ttf file
public な direct http(s) font asset URL
.ttf data URI
programmatic use における inline bytes

現行ルール:

明示的にサポートする custom font format は .ttf のみ
.otf と .ttc は reject される
fonts.googleapis.com/css* の stylesheet URL は reject される
unsafe/private/loopback な http(s) URL は reject される
explicit remote font fetch は 15 秒 timeout、32 MiB size limit で解決される
remote font failure は EFONT で返る

CJK 向けの自動 NotoSansJP 解決は、明示的な font source がないときだけ使われます。CJK を含み、font が cache されておらず、さらに自動解決が無効または不可能な場合は generate は EFONT で失敗します。

Structured Output と Exit Code

--json を付けると:

stdout は JSON のみになる
成功 payload は ok: true
failure payload は ok: false と error.code, error.message, 場合によっては error.details を含む
-v, --verbose の人間向け情報は引き続き stderr に出る

現行の exit code 区分:

コード	意味
`0`	成功
`1`	argument / validation / unsupported input failure
`2`	runtime / font-resolution failure
`3`	file I/O failure

典型的な使い方

official example から job を作成して、まず診断し、画像で確認してから PDF を作成します。

pdfme examples invoice --withInputs -o job.json
pdfme doctor job.json --json
pdfme generate job.json -o out.pdf --image --grid

既存 PDF を basePdf として使う overlay workflow:

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

インストール​

コマンド一覧​

pdfme generate​

pdfme validate​

pdfme doctor​

pdfme pdf2img​

pdfme pdf2size​

pdfme examples​

Font Contract​

Structured Output と Exit Code​

典型的な使い方​

インストール

コマンド一覧

`pdfme generate`

`pdfme validate`

`pdfme doctor`

`pdfme pdf2img`

`pdfme pdf2size`

`pdfme examples`

Font Contract

Structured Output と Exit Code

典型的な使い方