paperless-ngx-tools

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

{
  "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

node {baseDir}/scripts/search.mjs "query"

node {baseDir}/scripts/list.mjs [--limit N]

node {baseDir}/scripts/get.mjs <id> [--content]

node {baseDir}/scripts/upload.mjs <file> [--title "..."] [--tags "a,b"]

node {baseDir}/scripts/download.mjs <id> [--output path]

node {baseDir}/scripts/tags.mjs

node {baseDir}/scripts/types.mjs

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

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

"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.