Paperless

Interact with Paperless-NGX document management system via ppls CLI. Search, retrieve, upload, and organize documents.

Security Scan

The skill appears to do what it claims (wrap the ppls CLI for Paperless-NGX) and only requests appropriate credentials, but there is a minor metadata mismatch and you should verify the npm package and token handling before installing.

Purpose & Capability

The SKILL.md instructions and description match: they drive the ppls CLI to interact with Paperless-NGX (search, download, upload, metadata). However, registry-level metadata provided to you earlier shows no required binaries or env vars while the SKILL.md includes metadata that requires the ppls binary and env vars (PPLS_HOSTNAME, PPLS_TOKEN). This is likely a packaging/metadata omission rather than a functional mismatch, but it is an inconsistency you should be aware of.

Instruction Scope

Runtime instructions are narrowly scoped to installing/configuring/running the ppls CLI and using it to query and manage documents on a Paperless-NGX host. The doc tells the agent to run ppls commands and set hostname/token; it does not instruct reading unrelated files or exfiltrating data to third-party endpoints.

Install Mechanism

The SKILL.md recommends installing @nickchristensen/ppls via npm (global install). This is a common, expected mechanism for a CLI wrapper but is higher-risk than an instruction-only skill because it executes third-party code from npm. The referenced GitHub project exists (https://github.com/NickChristensen/ppls), which reduces but does not eliminate risk; you should review the package and prefer a trusted install method.

Credentials

The only credentials/configuration the skill needs (per SKILL.md metadata) are the Paperless hostname and API token (PPLS_HOSTNAME, PPLS_TOKEN), which are proportional to its purpose. No unrelated secrets or multiple service credentials are requested. Note again the registry metadata omitted these env requirements.

Persistence & Privilege

The skill does not request always:true, does not demand persistent elevated privileges, and does not attempt to change other skills' configurations. It appears to be an ordinary user-invocable skill with no special platform privileges.

Assessment

This skill looks coherent for controlling Paperless-NGX via the ppls CLI, but before installing: 1) Verify the npm package identity and maintainer (check the GitHub repo and package contents) to ensure you’re installing the legitimate @nickchristensen/ppls package. 2) Prefer installing without -g (or use a container/venv) if you want to limit global code execution, and avoid running npm as root. 3) Confirm where ppls stores the configured token (config file) and protect that file (restrict filesystem permissions); consider a least-privilege API token for Paperless. 4) Double-check the registry metadata mismatch (top-level metadata showed no required env vars/bins while SKILL.md does) — treat that as a packaging issue to clarify with the publisher. 5) If you cannot vet the package, consider manually invoking Paperless-NGX API calls or using a known trusted client instead.

Paperless-NGX CLI

Search and manage documents in Paperless-NGX using ppls.

Setup

npm install -g @nickchristensen/ppls
ppls config set hostname http://your-paperless-host
ppls config set token your-api-token

Searching Documents

# By name
ppls documents list --name-contains "invoice" --json

# By date range
ppls documents list --created-after 2024-01-01 --created-before 2024-12-31 --json

# By tag (OR — any of these tags)
ppls documents list --tag 5 --tag 12 --json

# By tag (AND — must have all)
ppls documents list --tag-all 5,12 --json

# Exclude tags
ppls documents list --tag-not 3 --json

# By correspondent
ppls documents list --correspondent 7 --json

# By document type
ppls documents list --document-type 2 --json

# Documents missing metadata
ppls documents list --no-correspondent --json
ppls documents list --no-tag --json

# Recently added/modified
ppls documents list --added-after 2024-06-01 --json
ppls documents list --modified-after 2024-06-01 --json

# Combine filters
ppls documents list --correspondent 7 --created-after 2024-01-01 --tag 5 --json

Viewing & Downloading

# Get full document details (includes OCR content)
ppls documents show 1234 --json

# Download single document
ppls documents download 1234 --output ~/Downloads/doc.pdf

# Download multiple documents
ppls documents download 1234 5678 --output-dir ~/Downloads

# Download original (pre-processed) version
ppls documents download 1234 --original

Uploading Documents

# Simple upload (Paperless auto-processes)
ppls documents add scan.pdf

# With metadata
ppls documents add receipt.pdf \
  --title "Store Receipt" \
  --correspondent 5 \
  --document-type 2 \
  --tag 10

Managing Metadata

# List tags/correspondents/document-types
ppls tags list --json
ppls correspondents list --json
ppls document-types list --json

# Create new
ppls tags add "Tax 2024" --color "#ff0000"
ppls correspondents add "New Vendor"
ppls document-types add "Contract"

# Update document metadata
ppls documents update 1234 --title "New Title" --correspondent 5 --tag 10

Tips

• Always use --json for AI/automation — it's the most parseable format
• Date formats: YYYY-MM-DD or full ISO 8601
• IDs are numeric — use list --json commands to find them
• Filters are repeatable: --tag 1 --tag 2 or --tag 1,2 both work
• Pagination: Use --page and --page-size for large result sets

Links

• ppls on GitHub
• Paperless-NGX Docs