# Fill a PDF Form from the Command Line

![banner](https://articles.aux4.blog/data/posts/aux4/fill-a-pdf-form-from-the-command-line/banner.webp)

## Introduction

Filling the same PDF form by hand — a signup sheet, an onboarding form, an application — is slow and easy to get wrong. This post builds a command-line workflow that reads a blank PDF form, fills its fields from a small JSON file, and writes out a finished copy, then wraps the whole thing into a reusable `aux4` command that downloads a form and fills it in one step.

## Install the packages

```bash
aux4 aux4 pkger install aux4/pdf aux4/curl
```

`aux4/pdf` uses [`qpdf`](https://qpdf.sourceforge.io) under the hood; the installer pulls it in for you.

## Step 1: download the form

You rarely start with the form on disk — it lives behind a URL. `aux4 curl request` fetches it, and a redirect writes the bytes to a file:

```bash
aux4 curl request https://example.com/forms/signup.pdf > form.pdf
```

```bash
file form.pdf
```

```text
form.pdf: PDF document, version 1.4, 1 pages
```

The download is byte-for-byte identical to the source, so the form you fill is exactly the form the sender published.

## Step 2: see what fields the form has

You can't fill a field you can't name. `aux4 pdf parse` lists every field with its name, type, and current value:

```bash
aux4 pdf parse form.pdf
```

```json
[
  {
    "page": 1,
    "fields": [
      { "name": "name", "value": "", "type": "TextField" },
      { "name": "email", "value": "", "type": "TextField" },
      { "name": "subscribe", "value": "Off", "type": "CheckBox" }
    ]
  }
]
```

Now you know the field names (`name`, `email`, `subscribe`) and their types — a text field takes a string, a checkbox takes a boolean. (`parse` reports a few more details per field, such as the on-page bounding box; the name, type, and value are what you need to fill it.)

## Step 3: fill it

`aux4 pdf fill` reads a JSON array of `{ name, value, type }` on standard input and writes a new PDF with `--out`. Text values are strings; a checkbox is a real boolean:

```bash
echo '[
  { "name": "name", "value": "Sally Ride", "type": "TextField" },
  { "name": "email", "value": "sally@example.com", "type": "TextField" },
  { "name": "subscribe", "value": true, "type": "CheckBox" }
]' | aux4 pdf fill form.pdf --out filled.pdf
```

```text
PDF filled and saved to filled.pdf
```

The original `form.pdf` is untouched; the filled copy is a brand-new file.

## Step 4: confirm it worked

Parse the *filled* file and read the values back — proof the fill landed, without opening a viewer:

```bash
aux4 pdf parse filled.pdf
```

```json
[
  {
    "page": 1,
    "fields": [
      { "name": "name", "value": "Sally Ride", "type": "TextField" },
      { "name": "email", "value": "sally@example.com", "type": "TextField" },
      { "name": "subscribe", "value": "Yes", "type": "CheckBox" }
    ]
  }
]
```

The text fields carry the values you set, and the checkbox flipped from `Off` to `Yes`.

## Step 5: make it a reusable command

Keep the field values in a file — `values.json` — so anyone can fill the form without hand-writing JSON on the command line:

```json
[
  { "name": "name", "value": "Sally Ride", "type": "TextField" },
  { "name": "email", "value": "sally@example.com", "type": "TextField" },
  { "name": "subscribe", "value": true, "type": "CheckBox" }
]
```

Then define a `form fetch` command in a local `.aux4` file that downloads a form and fills it in one shot:

```json
{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "form",
          "execute": [
            "profile:form"
          ],
          "help": {
            "text": "PDF form helpers"
          }
        }
      ]
    },
    {
      "name": "form",
      "commands": [
        {
          "name": "fetch",
          "execute": [
            "nout:aux4 curl request ${url} > form.pdf",
            "cat ${data} | aux4 pdf fill form.pdf --out ${out}"
          ],
          "help": {
            "text": "download a PDF form and fill it from a JSON data file",
            "variables": [
              { "name": "url", "text": "URL of the blank PDF form" },
              { "name": "data", "text": "JSON file with the field values" },
              { "name": "out", "text": "where to write the filled PDF", "default": "filled.pdf" }
            ]
          }
        }
      ]
    }
  ]
}
```

Now the whole workflow is one command:

```bash
aux4 form fetch --url https://example.com/forms/signup.pdf --data values.json --out filled.pdf
```

```text
PDF filled and saved to filled.pdf
```

## Conclusion

You went from a blank form behind a URL to a finished PDF without touching a mouse: `aux4/curl` downloads it, `aux4 pdf parse` reveals the field names, and `aux4 pdf fill` writes the values from a JSON file — verifiable by parsing the result. Wrapped as `aux4 form fetch`, it's a repeatable step you can drop into onboarding scripts, batch runs, or any pipeline that has to fill the same form again and again.

## See Also

- [aux4/pdf](https://hub.aux4.io/r/public/packages/aux4/pdf)
- [aux4/curl](https://hub.aux4.io/r/public/packages/aux4/curl)