Paperless-ngx Document Manager

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

Security Scan

The skill's code, instructions, and required credentials are consistent with a Paperless-ngx integration and do not request unrelated access or hidden network endpoints.

Purpose & Capability

Name/description match the included Node scripts and API reference. The requested env vars (PAPERLESS_URL, PAPERLESS_TOKEN) are exactly what a Paperless-ngx client needs; no unrelated services or binaries are requested.

Instruction Scope

SKILL.md and scripts confine actions to the Paperless API and user-specified filesystem paths (upload reads a given file; download writes to a chosen path). There are no instructions to read unrelated system files, other credentials, or to exfiltrate data to third-party domains; all network calls target ${PAPERLESS_URL}/api/.

Install Mechanism

No install spec is present (instruction + scripts only). Scripts require a Node.js environment to run, which is expected for .mjs files; nothing is downloaded from untrusted URLs or written to system locations by an installer.

Credentials

Only PAPERLESS_URL and PAPERLESS_TOKEN are required and the primary credential is the API token — appropriate for this integration. Note: the token grants access to documents and metadata on the Paperless instance, so treat it as sensitive.

Persistence & Privilege

always:false and there is no request to modify other skills or global agent configuration. The skill can be invoked autonomously by the agent (platform default), but it does not request elevated or persistent system privileges.

Assessment

This skill appears to do exactly what it says: it runs small Node scripts that call your Paperless-ngx API. Before installing, ensure you: (1) only provide a PAPERLESS_TOKEN for an account you trust because it can read/upload/delete documents; (2) have Node.js available to run the scripts; (3) review the included scripts (they are provided) and confirm PAPERLESS_URL points to your intended host (not a public or attacker-controlled URL); and (4) be cautious about file paths you pass to upload/download (they read/write user-specified files). If you want to limit risk, create a Paperless user with scoped permissions for automation rather than reusing a full-admin 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.