pput

Upload documents to a paperless-ngx instance from the command line.

A single bash script over the paperless REST API. It posts each file, then polls the task queue until the document is consumed, so you get a real result per file instead of a fire-and-forget task id.

Usage

pput FILE [FILE...]

$ pput fattura.pdf
OK   fattura.pdf -> doc 48

$ pput *.pdf
OK   bolletta.pdf -> doc 49
FAIL vecchia.pdf: duplicate of doc 12

Exit status is 0 when every file was consumed, 1 if any failed, timed out, or was unreadable. That makes it safe to chain:

pput scan.pdf && rm scan.pdf

Paperless rejects re-uploads of identical content, reported as duplicate of doc N.

File manager integration

pput.desktop adds an "Upload to Paperless" entry to the right-click menu for PDFs, for file managers that read the DES-EMA actions format (pcmanfm-qt, Caja, Nemo). It runs pput-gui, a wrapper that reports the result as a desktop notification, since a click has no terminal to print to. One file or a whole selection both work.

ln -s "$PWD/pput-gui" ~/bin/pput-gui
ln -s "$PWD/pput.desktop" ~/.local/share/file-manager/actions/pput.desktop

Exec= calls pput-gui by name, so it must be on the PATH your desktop session exports; use an absolute path there instead if it is not. Restart the file manager to pick up a new action.

Requirements

bash, curl, python3 (stdlib only)
pass holding a paperless API token

Configuration

The API token is read from pass, never passed on the command line. Create an entry with a token from the paperless web UI, under Settings, My Profile, API Token:

pass insert proxmox/paperless/api

Everything else is environment, with defaults baked in for the author's setup:

Variable	Default	Meaning
`PAPERLESS_URL`	`http://paperless.lan:8000`	base URL of the instance
`PAPERLESS_PASS_ENTRY`	`proxmox/paperless/api`	`pass` entry with the API token
`PAPERLESS_TIMEOUT`	`120`	seconds to wait per document

PAPERLESS_URL=https://paperless.example.org pput scan.pdf

Raise PAPERLESS_TIMEOUT if OCR of large scans outruns the default; the upload still succeeds server-side, only the wait gives up.

Note the API token is sent as a header, so an http:// instance transmits it in cleartext. Use it on a trusted network, or put the instance behind TLS.

Install

git clone <repo> ~/Programming/GIT/pput
ln -s ~/Programming/GIT/pput/pput ~/bin/pput

Tests

./test_status.sh

Checks the task-response parser against the shapes the paperless API returns: pending, success, duplicate, and other failures.

License

GPLv2. See LICENSE.

Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.