paperless

What This Skill Does

The paperless skill provides a direct command-line interface to your Paperless-NGX instance. It allows the OpenClaw agent to search, retrieve, organize, and upload digital documents effortlessly. By leveraging the ppls CLI, the agent acts as an automated clerk that can scan your repository, update document metadata, and batch-download files. This skill is essential for users who want to treat their document repository as a programmable database, enabling complex automation workflows like filtering invoices by date or auto-tagging new uploads.

Installation

1. Install the CLI dependency globally: npm install -g @nickchristensen/ppls
2. Configure your connection by running the following commands in your terminal:
   • ppls config set hostname http://your-paperless-host
   • ppls config set token your-api-token
3. Install the skill directly via OpenClaw: clawhub install openclaw/skills/skills/nickchristensen/paperless

Use Cases

• Automated Bookkeeping: Automatically pull all invoices received in the last month from specific correspondents and save them to a local financial report directory.
• Metadata Cleanup: Identify documents missing tags or correspondents and bulk-update them to maintain organization.
• Archival Workflows: Automatically download original files from Paperless-NGX to a cold storage backup location based on date ranges.
• Document Ingestion: Seamlessly upload files from a local scanner folder into Paperless-NGX with pre-configured titles and tags.

Example Prompts

1. "Find all documents from 'Energy Provider' received after January 1st, 2024, and download them to my ~/Documents/Utilities folder."
2. "Check for any documents in the system that do not have a tag and list their current IDs and titles."
3. "Upload the file 'Contract_Signed.pdf' from my desktop and tag it with 'Contracts' and '2024'."

Tips & Limitations

• Automation Friendly: Always include the --json flag when querying data. This ensures the output is structured for the AI to parse, preventing ambiguity when reading document lists or metadata.
• Data Integrity: When updating metadata, ensure you retrieve the correct numeric IDs using the list command first to avoid modifying the wrong documents.
• Performance: For large repositories, remember that the CLI supports pagination. If a search returns many results, use --page and --page-size to optimize the output load.
• Security: The skill requires an API token. Ensure that your token has appropriate permissions and store your credentials securely using your OS-level keychain or secret manager where possible.