{"content":"# aux4/pdf\n\nPDF toolkit\n\nA 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.\n\nThis 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.\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/pdf\n`\n\n## System Dependencies\n\nThis 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:\n\n- [brew](/r/public/packages/aux4/system-installer-brew)\n- [apt](/r/public/packages/aux4/system-installer-apt)\n\nFor more details, see [system-installer](/r/public/packages/aux4/pkger/commands/aux4/pkger/system).\n\n## Quick Start\n\nCount the number of pages in a PDF:\n\n`bash\naux4 pdf count sample.pdf\n`\n\nThis runs the package's page-count routine on sample.pdf and prints the page count to stdout.\n\n## Count pages\n\nOverview\n\nUse 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.\n\nExample\n\n`bash\naux4 pdf count invoice.pdf\n`\n\nFor command-specific details, see [aux4 pdf count](./commands/pdf/count).\n\n## Parse PDF\n\nOverview\n\nThe 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.\n\nExample\n\n`bash\naux4 pdf parse document.pdf\n`\n\nFor command-specific details, see [aux4 pdf parse](./commands/pdf/parse).\n\n## Fill a PDF (provide data on stdin)\n\nOverview\n\nThe 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).\n\nExample\n\nCreate a JSON array with field objects matching the template's fields (use aux4 pdf parse to discover field names and types):\n\nform-data.json:\n\n`json\n[\n {\"name\": \"Name\", \"value\": \"Jane Doe\", \"type\": \"TextField\"},\n {\"name\": \"Date\", \"value\": \"2025-01-15\", \"type\": \"TextField\"},\n {\"name\": \"Amount\", \"value\": \"$123.45\", \"type\": \"TextField\"}\n]\n`\n\nThen run:\n\n`bash\ncat form-data.json | aux4 pdf fill template.pdf --out filled.pdf\n`\n\nThis reads the JSON payload from stdin, fills template.pdf, and writes the result to filled.pdf.\n\nFor command-specific details, see [aux4 pdf fill](./commands/pdf/fill).\n\n## Add form fields\n\nOverview\n\nThe 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.\n\nExample\n\nCreate a JSON description of form fields:\n\nfields.json:\n\n`json\n[\n {\n \"name\": \"customer_name\",\n \"type\": \"TextField\",\n \"page\": 1,\n \"x\": 50,\n \"y\": 700,\n \"width\": 300,\n \"height\": 20\n },\n {\n \"name\": \"invoice_date\",\n \"type\": \"TextField\",\n \"page\": 1,\n \"x\": 400,\n \"y\": 700,\n \"width\": 120,\n \"height\": 20\n }\n]\n`\n\nThen run:\n\n`bash\ncat fields.json | aux4 pdf form template.pdf --out template-with-fields.pdf\n`\n\nFor command-specific details, see [aux4 pdf form](./commands/pdf/form).\n\n## Convert a PDF page to an image\n\nOverview\n\nThe 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.\n\nExample\n\n`bash\naux4 pdf image brochure.pdf --page 2 --image page2.png\n`\n\nThis converts page 2 of brochure.pdf into page2.png.\n\nFor command-specific details, see [aux4 pdf image](./commands/pdf/image).\n\n## Protect a PDF with a password\n\nOverview\n\nThe 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).\n\nExample\n\n`bash\naux4 pdf protect document.pdf --password secret123 --out protected.pdf\n`\n\nFor command-specific details, see [aux4 pdf protect](./commands/pdf/protect).\n\n## Remove password protection from a PDF\n\nOverview\n\nThe 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).\n\nExample\n\n`bash\naux4 pdf unprotect protected.pdf --password secret123 --out decrypted.pdf\n`\n\nFor command-specific details, see [aux4 pdf unprotect](./commands/pdf/unprotect).\n\n## Examples\n\n### Fill a template with JSON data\n\nThis 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:\n\n`bash\ncat data/employee-onboarding.json | aux4 pdf fill onboarding-template.pdf --out onboarding-filled.pdf\n`\n\nThe filled PDF is written to onboarding-filled.pdf.\n\n### Add form fields to a template\n\nUse a JSON array describing fields and pipe it to the form command:\n\n`bash\ncat data/fields.json | aux4 pdf form blank-form.pdf --out blank-form-with-fields.pdf\n`\n\nThis creates blank-form-with-fields.pdf with the new form fields applied.\n\n### Convert multiple pages to images\n\nConvert the first three pages of a PDF to sequential images (example using a loop):\n\n`bash\naux4 pdf image report.pdf --page 1 --image report-page-1.png\naux4 pdf image report.pdf --page 2 --image report-page-2.png\naux4 pdf image report.pdf --page 3 --image report-page-3.png\n`\n\nEach command writes the specified page to the given PNG file.\n\n### Protect and unprotect a PDF\n\nEncrypt a PDF with a password and then decrypt it:\n\n`bash\naux4 pdf protect report.pdf --password mySecret --out report-protected.pdf\naux4 pdf unprotect report-protected.pdf --password mySecret --out report-decrypted.pdf\n`\n\nNote: other commands (count, parse, fill, form, image) will show an error if the PDF is password-protected. Use aux4 pdf unprotect` first.\n\n## License\n\nThis package is licensed under the Apache-2.0 License.\n\nSee LICENSE for details.\n"}