paperless-ngx

# Paperless-ngx Document management via Paperless-ngx REST API. ## Configuration Set environment variables in `~/.clawdbot/clawdbot.json`: ```json { "env": { "PAPERLESS_URL": "http://your-paperless-host:8000", "PAPERLESS_TOKEN": "your-api-token" } } ``` Or configure via the skills entry (allows using `apiKey` shorthand): ```json { "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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash node {baseDir}/scripts/search.mjs "invoice" | jq '.results[] | {id, title, created}' ``` ## Advanced Usage For complex queries or bulk operations, see [references/api.md](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.