home / skills / openclaw / skills / paperless-docs

paperless-docs skill

safe

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

npx playbooks add skill openclaw/skills --skill paperless-docs

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 Paperless-ngx via its REST API, letting you search, upload, tag, and retrieve documents programmatically. It provides a set of ready-to-run scripts for common tasks and outputs JSON for easy integration into automation pipelines. Configure with your Paperless URL and API token to get started quickly.

How this skill works

The skill uses environment variables (PAPERLESS_URL and PAPERLESS_TOKEN) or an apiKey entry to authenticate to your Paperless-ngx instance. Scripts implement search, list, get, upload, download, and metadata management operations and return JSON so you can pipe results into tools like jq or other automation. Advanced users can call the underlying API patterns directly for bulk or custom operations.

When to use it

Automate document ingestion from scanners or other systems.
Build integrations that need full-text search of archived documents.
Quickly retrieve PDFs or original files for workflows or audits.
Maintain tags, correspondents, and document types via scripts.
Script bulk exports or metadata updates for backups or migrations.

Best practices

Store PAPERLESS_URL and PAPERLESS_TOKEN in ~/.clawdbot/clawdbot.json or an env var, never in source control.
Use the JSON output with jq to extract only needed fields for downstream processing.
Combine filters (query, tag, type, correspondent) to reduce API responses and speed up workflows.
Regenerate tokens from the Paperless web UI if you encounter 401 errors.
When uploading, include meaningful metadata (title, tags, type, correspondent, created) to improve discoverability.

Example use cases

Daily job that uploads new invoices from a network folder and tags them for accounting.
Chatbot integration that searches for a document by text and returns a download link or PDF.
Scheduled export that lists recent documents and saves PDFs to a backup location.
CLI-driven audit: list documents with a specific tag and print metadata for review.
Bulk metadata correction: list documents by type then update tags or correspondents via script.

FAQ

How do I get the API token?

Generate it from Paperless-ngx web UI under Settings → Users & Groups → [your user] → Generate Token, then place it in your config or env.

Why am I seeing 'PAPERLESS_URL not set' or connection refused?

Ensure PAPERLESS_URL includes the correct host and port and that Paperless-ngx is running and reachable from the machine running the scripts.