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.
