paperless-ngx

name	paperless-ngx
description	Manage documents in Paperless-ngx - search, upload, tag, and retrieve.
homepage	https://github.com/paperless-ngx/paperless-ngx
metadata	{"clawdbot":{"requires":{"env":["PAPERLESS_URL","PAPERLESS_TOKEN"]},"primaryEnv":"PAPERLESS_TOKEN"}}

Paperless-ngx

Document management via Paperless-ngx REST API.

Configuration

Set environment variables in ~/.clawdbot/clawdbot.json:

{
  "env": {
    "PAPERLESS_URL": "http://your-paperless-host:8000",
    "PAPERLESS_TOKEN": "your-api-token"
  }
}

Or configure via the skills entry (allows using apiKey shorthand):

{
  "skills": {
    "entries": {
      "paperless-ngx": {
        "env": { "PAPERLESS_URL": "http://your-paperless-host:8000" },
        "apiKey": "your-api-token"
      }
    }
  }
}

Get your API token from Paperless web UI: Settings → Users & Groups → [user] → Generate Token.

Quick Reference

Task	Command
Search documents	node {baseDir}/scripts/search.mjs "query"
List recent	node {baseDir}/scripts/list.mjs [--limit N]
Get document	node {baseDir}/scripts/get.mjs <id> [--content]
Upload document	node {baseDir}/scripts/upload.mjs <file> [--title "..."] [--tags "a,b"]
Download PDF	node {baseDir}/scripts/download.mjs <id> [--output path]
List tags	node {baseDir}/scripts/tags.mjs
List types	node {baseDir}/scripts/types.mjs
List correspondents	node {baseDir}/scripts/correspondents.mjs

All scripts are in {baseDir}/scripts/.

Common Workflows

Find a document

# Full-text search
node {baseDir}/scripts/search.mjs "electricity bill december"

# Filter by tag
node {baseDir}/scripts/search.mjs --tag "tax-deductible"

# Filter by document type
node {baseDir}/scripts/search.mjs --type "Invoice"

# Filter by correspondent
node {baseDir}/scripts/search.mjs --correspondent "AGL"

# Combine filters
node {baseDir}/scripts/search.mjs "2025" --tag "unpaid" --type "Invoice"

Get document details

# Metadata only
node {baseDir}/scripts/get.mjs 28

# Include OCR text content
node {baseDir}/scripts/get.mjs 28 --content

# Full content (no truncation)
node {baseDir}/scripts/get.mjs 28 --content --full

Upload a document

# Basic upload (title auto-detected)
node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf

# With metadata
node {baseDir}/scripts/upload.mjs /path/to/invoice.pdf \
  --title "AGL Electricity Jan 2026" \
  --tags "unpaid,utility" \
  --type "Invoice" \
  --correspondent "AGL" \
  --created "2026-01-15"

Download a document

# Download to current directory
node {baseDir}/scripts/download.mjs 28

# Specify output path
node {baseDir}/scripts/download.mjs 28 --output ~/Downloads/document.pdf

# Get original (not archived/OCR'd version)
node {baseDir}/scripts/download.mjs 28 --original

Manage metadata

# List all tags
node {baseDir}/scripts/tags.mjs

# List document types
node {baseDir}/scripts/types.mjs

# List correspondents
node {baseDir}/scripts/correspondents.mjs

# Create new tag
node {baseDir}/scripts/tags.mjs --create "new-tag-name"

# Create new correspondent
node {baseDir}/scripts/correspondents.mjs --create "New Company Name"

Output Format

All scripts output JSON for easy parsing. Use jq for formatting:

node {baseDir}/scripts/search.mjs "invoice" | jq '.results[] | {id, title, created}'

Advanced Usage

For complex queries or bulk operations, see references/api.md for direct API access patterns.

Troubleshooting

"PAPERLESS_URL not set" — Add to ~/.clawdbot/clawdbot.json env section or export in shell.

"401 Unauthorized" — Check PAPERLESS_TOKEN is valid. Regenerate in Paperless UI if needed.

"Connection refused" — Verify Paperless is running and URL is correct (include port).

Upload fails silently — Check Paperless logs; file may be duplicate or unsupported format.