decrypt-pdf

• Install via Homebrew
• Quick Start
• Dependencies
• Usage
  • Options
  • Exit Codes
• Specifying the Password
• Running Tests
• Automator Quick Action (macOS)
• Design
• TODO

A command-line tool that decrypts password-protected PDF files using a cascading strategy of tools: qpdf, mutool, and ghostscript. It tries each tool in sequence until one succeeds — so you don't have to remember which tool works for which PDF.

This is not a password cracker. It assumes you already know the password.

The simplest way to use it through homebrew

brew tap sdaas/tap
brew install decrypt-pdf

This also contains instructions on how how to install it as an Automator script and launch it via right-clicking on the file in Finder

Quick Start

# Using the -p flag
./decrypt-pdf -p 's3cret' document.pdf

# Using an environment variable
export DECRYPT_PASSWORD='s3cret'
./decrypt-pdf document.pdf

The decrypted file is written to document_decrypted.pdf by default, or you can specify an output path:

./decrypt-pdf -p 's3cret' document.pdf /tmp/unlocked.pdf

Dependencies

Install at least one (all three recommended):

brew install qpdf
brew install mupdf-tools
brew install ghostscript

Usage

decrypt-pdf [OPTIONS] [-p PASSWORD] INPUT_FILE [OUTPUT_FILE]

Options

Flag	Description
-p PASSWORD	Password for the encrypted PDF
--verbose	Show detailed output from each decryption tool
--quiet, -q	Suppress all output; rely on exit code and output file
-h, --help	Show help message

Exit Codes

Code	Meaning
0	Success (or file is already unencrypted)
1	Failure

Specifying the Password

The password can be provided in two ways:

1. -p flag (highest priority) — passed directly on the command line. Simple but visible in ps output and shell history.

   ./decrypt-pdf -p 's3cret' document.pdf

2. DECRYPT_PASSWORD environment variable — used as a fallback when -p is not provided. Avoids exposing the password on the command line.

   export DECRYPT_PASSWORD='s3cret'
   ./decrypt-pdf document.pdf

   Or inline for a single invocation:

   DECRYPT_PASSWORD='s3cret' ./decrypt-pdf document.pdf

Precedence: -p flag > DECRYPT_PASSWORD env var > error.

Running Tests

# 1. Create a .env file with the test password (see .env.example)
cp .env.example .env
# Edit .env and set TEST_DECRYPT_PASSWORD=<your-password>

# 2. Run the test suite
./test-decrypt-pdf.sh

Tests that require the password will be skipped if TEST_DECRYPT_PASSWORD is not set. The .env file is gitignored and should never be committed.

Automator Quick Action (macOS)

You can set up a macOS Quick Action so that you can right-click any PDF in Finder and decrypt it — no terminal required.

One-Time Setup

1. Copy the decryption script into the workflow bundle:

   mkdir -p ~/Library/Services/"Decrypt PDF File.workflow"/Contents/
   cp decrypt-pdf ~/Library/Services/"Decrypt PDF File.workflow"/Contents/

2. Open Automator and select Quick Action as the document type.

3. At the top, set "Workflow receives current PDF files in Finder".

4. From the actions library, drag Run AppleScript into the workflow.

5. Replace the default script with the contents of automator/decrypt-pdf.applescript.

6. File > Save and name it "Decrypt PDF File".

How to Use

Right-click a PDF in Finder > Quick Actions > Decrypt PDF File. A dialog will prompt for the password. The decrypted file appears in the same folder as <filename>_decrypted.pdf.

Design

See design.md for details on the decryption strategy, tool-specific notes (qpdf, mutool, ghostscript), and the cascading workflow.

TODO

• Automator integration for macOS (done — see Automator Quick Action)
• Create and Publish Homebrew package (done — see Install via Homebrew)