paperless-ngx-tools

Manage documents in Paperless-ngx - search, upload, tag, and retrieve.

Security Scan

The skill's files, instructions, and required secrets are coherent for a Paperless-ngx client; nothing requests unrelated credentials or external endpoints, though it omits declaring the need for the Node runtime.

Purpose & Capability

Name/description, API reference, and scripts all align with managing Paperless-ngx documents. One mismatch: the package includes NodeJS scripts and the SKILL.md shows commands like `node {baseDir}/scripts/...`, but the registry metadata lists no required binaries — it should declare `node` (or `nodejs`) as a required binary.

Instruction Scope

SKILL.md instructs the agent to call local scripts and document the two env vars. The scripts only access PAPERLESS_URL/PAPERLESS_TOKEN and the Paperless API, read/write local files for upload/download, and fetch metadata — all within the expected scope.

Install Mechanism

No install spec is provided (instruction + bundled scripts). No remote downloads or archive extraction are performed by the skill. This lowers installation risk.

Credentials

Only PAPERLESS_URL and PAPERLESS_TOKEN are required and the primary credential is PAPERLESS_TOKEN — appropriate and proportional for talking to a Paperless-ngx instance.

Persistence & Privilege

always: false and no special persistence or cross-skill/system configuration changes. The skill does perform file I/O (upload/download) as expected, but it does not request elevated or persistent privileges.

Assessment

This skill appears to do what it claims: run the included Node scripts to manage Paperless-ngx via its API. Before installing: 1) Ensure you have Node.js available locally (SKILL.md uses `node` but the registry entry didn't list it). 2) Only set PAPERLESS_URL to a trusted Paperless host and store PAPERLESS_TOKEN securely (the token gives API access to your documents). 3) Review the uploaded/download paths you use (the scripts will read local files for upload and write files for download). 4) Because the skill can be invoked by the agent, consider whether you want autonomous runs using that token; revoke/regenerate the token in Paperless if you later stop using the skill. If you need higher assurance, inspect the bundled scripts yourself (they are included) before running.

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.