Paperless-NGX CLI

Search and manage documents in your Paperless-NGX installation using the ppls CLI.

What is Paperless-NGX?

Paperless-NGX is a document management system that scans, OCRs, and organizes your documents. The ppls CLI provides command-line access to search, download, upload, and manage your paperless library.

Setup

Install via npm/bun:

npm install -g @nickchristensen/ppls
# or
bun add -g @nickchristensen/ppls

Configure connection:

ppls config set hostname http://your-paperless-host
ppls config set token your-api-token

Or use environment variables:

export PPLS_HOSTNAME=http://your-paperless-host
export PPLS_TOKEN=your-api-token

Common Commands

Search Documents

# Search by name/title
ppls documents list --name-contains "invoice" --json

# Search by specific IDs
ppls documents list --id-in 1234,5678 --json

# Paginate results
ppls documents list --page 2 --page-size 50 --json

# Sort results
ppls documents list --sort created --json

Get Document Details

# Show full document metadata (including OCR'd content)
ppls documents show 1234 --json

# Get just the basics
ppls documents show 1234 --plain

Download Documents

# Download single file
ppls documents download 1234

# Download to path
ppls documents download 1234 --output /tmp/document.pdf

# Download multiple documents
ppls documents download 1234,5678

# Download multiple documents to path
ppls documents download 1234,5678 --output-dir ~/tmp

Upload Documents

# Upload with metadata
ppls documents add receipt.pdf \
  --title "Store Receipt" \
  --correspondent 5 \
  --document-type 2 \
  --tag 10

# Upload without metadata (will be processed by Paperless)
ppls documents add scan.pdf

Manage Tags

# List all tags
ppls tags list --json

# Create a new tag
ppls tags add "Tax Documents" --color "#ff0000"

# Search tags by name
ppls tags list --name-contains "tax" --json

Manage Correspondents

# List all correspondents
ppls correspondents list --json

# Create new correspondent
ppls correspondents add "New Vendor"

Common Use Cases

"Find documents with 'tax' in the name"

ppls documents list --name-contains "tax" --json

"Show me all invoices"

ppls documents list --name-contains "invoice" --json

"Download a specific document"

ppls documents show 1234 --json  # Get details first
ppls documents download 1234 --output doc.pdf

"Add a scanned receipt with metadata"

ppls documents add receipt.pdf --title "Grocery Receipt" --tag 25 --correspondent 5

"Search for specific text in OCR'd content"

# Get all docs, then search the content field
ppls documents list --json | jq '.[] | select(.content | contains("warranty"))'

Output Formats

ppls supports multiple output formats:

--json - Machine-readable JSON (best for scripts/AI)
--plain - Plain text (simple, parseable)
--table - Formatted table (human-readable)

For AI/automation, always use --json

Tips

JSON output: Parse with jq for complex queries
Date format: Customize with --date-format (uses date-fns tokens)
Pagination: Use --page-size and --page for large result sets
IDs: Most commands accept numeric IDs (tags, correspondents, documents)

paperless