playbooks

home / skills / michaelvessia / nixos-config / paperless

paperless skill

/modules/programs/claude-code/skills/paperless

This skill helps you search, organize, and access documents in Paperless-ngx using CLI to manage invoices, receipts, and files.

npx playbooks add skill michaelvessia/nixos-config --skill paperless

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.3 KB
---
name: paperless
description: Search and manage documents in Paperless-ngx document management system. Use when the user asks about documents, invoices, receipts, tax forms, bills, or wants to search their document library.
allowed-tools: Bash, Read
---

# Paperless-ngx

Interact with Paperless-ngx document management system via CLI.

## Setup

Environment: `~/.secrets.env` (PAPERLESS_URL, PAPERLESS_TOKEN) - loaded by
wrapper.

## CLI Discovery

Run `paperless-cli --help` to see available commands. Run
`paperless-cli <command> --help` for detailed usage of any command.

## Capabilities

The CLI supports:

- **Search**: Full-text search with filters (date ranges, tags, correspondents)
- **Browse**: List recent documents, inbox items
- **Read**: Get document details and extracted text content
- **Organize**: Add/remove tags, edit metadata (title, correspondent, type)
- **Find related**: Discover similar documents
- **Download**: Save original files locally
- **Metadata**: List tags, correspondents, document types, stats

## Workflow

1. Search or list to find documents
2. Get document by ID to read full content
3. Add/remove tags to organize
4. Find similar documents for related items
5. Download originals when needed

## Notes

- Flags must come BEFORE positional arguments
- Document IDs are integers returned from search/list results

Overview

This skill integrates with Paperless-ngx to search, read, organize, and download documents from your document management library. It exposes common CLI operations so you can find invoices, receipts, tax forms, and other documents quickly and manage metadata and tags from conversational prompts. Use it to streamline document retrieval and lightweight library maintenance without leaving your chat flow.

How this skill works

The skill issues Paperless-ngx CLI commands (paperless-cli) using credentials provided in a secrets environment file and parses results to present document lists, metadata, and extracted text. It supports full-text search with filters, listing recent or inbox items, reading document details and OCR text, editing metadata and tags, finding related documents, and downloading originals. Command flags must be placed before positional arguments and document IDs are integers from search/list outputs.

When to use it

  • Locate invoices, receipts, bills, or tax forms across your document library.
  • Retrieve OCR-extracted text or full document details for a specific file.
  • Add or remove tags and edit metadata to keep the archive organized.
  • Find documents similar to a selected record (related receipts, invoices).
  • Download original files for sharing or local processing.

Best practices

  • Keep PAPERLESS_URL and PAPERLESS_TOKEN in a secure ~/.secrets.env file loaded by the wrapper.
  • Run searches first to obtain the document ID before issuing metadata or download commands.
  • Place CLI flags before positional arguments to avoid incorrect parsing.
  • Use date ranges, tags, and correspondents filters to narrow search results and reduce noise.
  • Verify changes (list or read document) after editing metadata or tags to confirm updates.

Example use cases

  • Search for all receipts tagged "travel" from last month and download originals for expense reporting.
  • Find a specific invoice by supplier name and extract the OCR text to copy payment details.
  • List new inbox items, tag them with project codes, and move them into the proper document type.
  • Discover documents similar to a selected contract to gather related signed copies.
  • Bulk-update correspondent or document type metadata after a company reorganization.

FAQ

How does the skill authenticate to Paperless-ngx?

It uses PAPERLESS_URL and PAPERLESS_TOKEN stored in a ~/.secrets.env file loaded by the wrapper; ensure those variables are set and valid.

What format are document IDs and how do I find them?

Document IDs are integers returned by search or list commands; run a search or list to get the ID before read, tag, or download actions.