home / skills / openclaw / skills / paperless-ngx-tools

paperless-ngx-tools skill

safe

/skills/madmantim/paperless-ngx-tools

This skill helps you manage documents in Paperless-ngx by searching, uploading, tagging, and retrieving via REST API.

npx playbooks add skill openclaw/skills --skill paperless-ngx-tools

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

Files (11)

SKILL.md

3.9 KB

---
name: paperless-ngx
description: Manage documents in Paperless-ngx - search, upload, tag, and retrieve.
homepage: https://github.com/paperless-ngx/paperless-ngx
metadata: {"clawdbot":{"requires":{"env":["PAPERLESS_URL","PAPERLESS_TOKEN"]},"primaryEnv":"PAPERLESS_TOKEN"}}
---

# Paperless-ngx

Document management via Paperless-ngx REST API.

## Configuration

Set environment variables in `~/.clawdbot/clawdbot.json`:

```json
{
  "env": {
    "PAPERLESS_URL": "http://your-paperless-host:8000",
    "PAPERLESS_TOKEN": "your-api-token"
  }
}
```

Or configure via the skills entry (allows using `apiKey` shorthand):

```json
{
  "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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
node {baseDir}/scripts/search.mjs "invoice" | jq '.results[] | {id, title, created}'
```

## Advanced Usage

For complex queries or bulk operations, see [references/api.md](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.

Overview

This skill manages documents in a Paperless-ngx instance, letting you search, upload, tag, and retrieve files via convenient command-line scripts. It uses the Paperless-ngx REST API and outputs JSON for easy automation. Configure the service URL and API token once, then run scripts to integrate document management into workflows.

How this skill works

The skill provides a set of Node scripts that call Paperless-ngx endpoints to perform searches, list recent documents, get metadata and OCR content, upload files with metadata, download originals or archived PDFs, and manage tags, types, and correspondents. You supply PAPERLESS_URL and PAPERLESS_TOKEN via environment configuration or the skill entry, and all script output is JSON so it can be piped to jq or other tools. Advanced operations can call the API directly for bulk and complex queries.

When to use it

Index and search scanned invoices, receipts, and letters stored in Paperless-ngx.
Automate uploads from a folder or ingest pipeline with metadata and tags.
Fetch OCR text for automated extraction or downstream processing.
Download originals or archived PDFs for backups or auditing.
List and manage tags, document types, and correspondents programmatically.

Best practices

Set PAPERLESS_URL and PAPERLESS_TOKEN in the global environment config to avoid repeating credentials.
Use JSON output and tools like jq to parse and integrate results into scripts and CI jobs.
Include metadata (title, tags, type, correspondent, created date) at upload to improve searchability.
Limit API rate and batch uploads to avoid overloading the Paperless instance during bulk operations.
Regenerate the API token from the Paperless web UI if you encounter 401 Unauthorized errors.

Example use cases

Full-text search for a specific bill and download the PDF for accounting.
Automatic daily upload of scanned receipts with tags for expense tracking.
Bulk export of documents for offsite backup by listing recent items and downloading originals.
Create a workflow that filters unpaid invoices by tag and sends reminders.
Build a dashboard that lists recent documents, tags, and correspondents via the JSON API.

FAQ

How do I get the API token?

Generate a token in the Paperless web UI under Settings → Users & Groups → [user] → Generate Token.

Why am I getting connection refused?

Verify PAPERLESS_URL is correct, includes the port, and that the Paperless service is running and reachable from your host.