# Password-Protect (and Unlock) PDFs from the Command Line

![banner](https://articles.aux4.blog/data/posts/aux4/password-protect-and-unlock-pdfs/banner.webp)

## Introduction

Some PDFs shouldn't travel unlocked — contracts, invoices, payslips, anything with a name and a number on it. This post encrypts a PDF with a password straight from the terminal, proves the protection is real by watching an ordinary read fail, then unlocks it again — and wraps it into a one-word `aux4 lock` command.

## Install the package

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

`aux4/pdf` shells out to [`qpdf`](https://qpdf.sourceforge.io) for encryption; the installer brings it along.

## Step 1: confirm the file is readable

Start with a normal PDF. `aux4 pdf count` reports its page count — a quick "before" that proves the file is open:

```bash
aux4 pdf count doc.pdf
```

```text
1
```

## Step 2: lock it

`aux4 pdf protect` encrypts the file with a password and writes the locked copy to `--out`:

```bash
aux4 pdf protect doc.pdf --password s3cret --out locked.pdf
```

```text
PDF protected and saved to locked.pdf
```

Always pass `--out` a different path — the original `doc.pdf` stays as-is, and `locked.pdf` is the encrypted one.

## Step 3: prove it's actually locked

This is the part that matters. Try to read the protected file the same way you read the original, and `aux4/pdf` refuses:

```bash
aux4 pdf count locked.pdf
```

```text
The PDF file is password-protected. Use 'aux4 pdf unprotect' to remove protection first.
```

Every read command — `count`, `text`, `parse`, `image` — hits the same wall. The content is genuinely encrypted, not just flagged "read-only."

## Step 4: unlock it

Given the password, `aux4 pdf unprotect` writes a decrypted copy:

```bash
aux4 pdf unprotect locked.pdf --password s3cret --out unlocked.pdf
```

```text
PDF unprotected and saved to unlocked.pdf
```

And the unlocked copy reads normally again — same page count as the original:

```bash
aux4 pdf count unlocked.pdf
```

```text
1
```

## Step 5: the wrong password gets nothing

To show the encryption is real, try to unlock with the wrong password. The command fails — the decisive line in the error is:

```text
qpdf: locked.pdf: invalid password
```

And, crucially, no output file is written:

```bash
aux4 pdf unprotect locked.pdf --password wrongone --out nope.pdf
ls nope.pdf
```

```text
ls: nope.pdf: No such file or directory
```

Without the password, the content stays sealed — which is the whole point.

## Step 6: make it a one-word command

A short `.aux4` command turns "protect this file" into `aux4 lock report.pdf --password ...`. It defaults the output to a `.locked.pdf` sibling so you never accidentally overwrite the original:

```json
{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "lock",
          "execute": [
            "aux4 pdf protect ${file} --password ${password} --out ${out}"
          ],
          "help": {
            "text": "Password-protect a PDF",
            "variables": [
              { "name": "file", "text": "The PDF file to lock", "arg": true },
              { "name": "password", "text": "The password to encrypt with" },
              { "name": "out", "text": "Where to save the locked PDF", "default": "${file}.locked.pdf" }
            ]
          }
        }
      ]
    }
  ]
}
```

```bash
aux4 lock report.pdf --password hunter2
```

```text
PDF protected and saved to report.pdf.locked.pdf
```

## Conclusion

Locking a PDF is now a single command, and so is opening it again: `aux4 pdf protect` encrypts with a password, every read command refuses the file until it's unlocked, and `aux4 pdf unprotect` restores it — with the wrong password getting exactly nothing. Wrapped as `aux4 lock`, it's the last step you run before a sensitive document leaves your machine.

## See Also

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