Skip to content

README.md

Latest commit

 

History

History
228 lines (143 loc) · 6.43 KB

README.md

File metadata and controls

228 lines (143 loc) · 6.43 KB

aux4/pdf

PDF toolkit

A small set of aux4 commands for inspecting and manipulating PDF files. This package exposes utilities to count pages, parse PDF structure, fill PDFs with data, add form fields, render PDF pages to images, and password-protect or unprotect PDFs.

This package is useful for automation workflows that need quick, scriptable PDF operations (page counts, extracting structure, filling templates, adding form fields, exporting pages as images) and fits into the aux4 ecosystem as a lightweight PDF helper that can be composed with other aux4 packages and scripts.

Installation

aux4 aux4 pkger install aux4/pdf

System Dependencies

This package requires system-level tools in some operations. You need to have one of the following system installers available for the dependencies referenced by the package:

For more details, see system-installer.

Quick Start

Count the number of pages in a PDF:

aux4 pdf count sample.pdf

This runs the package's page-count routine on sample.pdf and prints the page count to stdout.

Count pages

Overview

Use the count command to quickly determine the number of pages in a PDF file. This is a minimal, fast operation useful in scripts and CI checks.

Example

aux4 pdf count invoice.pdf

For command-specific details, see aux4 pdf count.

Parse PDF

Overview

The parse command extracts and prints parsed PDF information produced by the package parser. Use it when you need to inspect the PDF structure or extract metadata the parser exposes.

Example

aux4 pdf parse document.pdf

For command-specific details, see aux4 pdf parse.

Fill a PDF (provide data on stdin)

Overview

The fill command accepts data on stdin and applies it to a PDF template, producing a filled PDF. Provide the template PDF as a positional argument. Optionally pass an output location using the out variable (if omitted, the filled PDF will be saved next to the original file).

Example

Create a JSON array with field objects matching the template's fields (use aux4 pdf parse to discover field names and types):

form-data.json:

[
  {"name": "Name", "value": "Jane Doe", "type": "TextField"},
  {"name": "Date", "value": "2025-01-15", "type": "TextField"},
  {"name": "Amount", "value": "$123.45", "type": "TextField"}
]

Then run:

cat form-data.json | aux4 pdf fill template.pdf --out filled.pdf

This reads the JSON payload from stdin, fills template.pdf, and writes the result to filled.pdf.

For command-specific details, see aux4 pdf fill.

Add form fields

Overview

The form command accepts field definitions from stdin and adds form fields to a PDF. Use this to programmatically add or modify form structures before distributing templates.

Example

Create a JSON description of form fields:

fields.json:

[
  {
    "name": "customer_name",
    "type": "TextField",
    "page": 1,
    "x": 50,
    "y": 700,
    "width": 300,
    "height": 20
  },
  {
    "name": "invoice_date",
    "type": "TextField",
    "page": 1,
    "x": 400,
    "y": 700,
    "width": 120,
    "height": 20
  }
]

Then run:

cat fields.json | aux4 pdf form template.pdf --out template-with-fields.pdf

For command-specific details, see aux4 pdf form.

Convert a PDF page to an image

Overview

The image command converts a page from a PDF into an image file. Provide the PDF as the positional argument and optionally use --page and --image to select the page and output filename. If --image is omitted, the image will be saved next to the source PDF.

Example

aux4 pdf image brochure.pdf --page 2 --image page2.png

This converts page 2 of brochure.pdf into page2.png.

For command-specific details, see aux4 pdf image.

Protect a PDF with a password

Overview

The protect command encrypts a PDF file with a password using 256-bit AES encryption. Provide the PDF as the positional argument and use --password to set the encryption password. Use --out to specify the output file (if omitted, the original file is overwritten).

Example

aux4 pdf protect document.pdf --password secret123 --out protected.pdf

For command-specific details, see aux4 pdf protect.

Remove password protection from a PDF

Overview

The unprotect command decrypts a password-protected PDF. Provide the encrypted PDF as the positional argument and use --password with the correct password. Use --out to specify the output file (if omitted, the original file is overwritten).

Example

aux4 pdf unprotect protected.pdf --password secret123 --out decrypted.pdf

For command-specific details, see aux4 pdf unprotect.

Examples

Fill a template with JSON data

This example shows filling a template using JSON input read from a file. Create the JSON payload (see the Quick Start example) and then pipe it to the fill command:

cat data/employee-onboarding.json | aux4 pdf fill onboarding-template.pdf --out onboarding-filled.pdf

The filled PDF is written to onboarding-filled.pdf.

Add form fields to a template

Use a JSON array describing fields and pipe it to the form command:

cat data/fields.json | aux4 pdf form blank-form.pdf --out blank-form-with-fields.pdf

This creates blank-form-with-fields.pdf with the new form fields applied.

Convert multiple pages to images

Convert the first three pages of a PDF to sequential images (example using a loop):

aux4 pdf image report.pdf --page 1 --image report-page-1.png
aux4 pdf image report.pdf --page 2 --image report-page-2.png
aux4 pdf image report.pdf --page 3 --image report-page-3.png

Each command writes the specified page to the given PNG file.

Protect and unprotect a PDF

Encrypt a PDF with a password and then decrypt it:

aux4 pdf protect report.pdf --password mySecret --out report-protected.pdf
aux4 pdf unprotect report-protected.pdf --password mySecret --out report-decrypted.pdf

Note: other commands (count, parse, fill, form, image) will show an error if the PDF is password-protected. Use aux4 pdf unprotect first.

License

This package is licensed under the Apache-2.0 License.

See LICENSE for details.