# pput

Upload documents to a [paperless-ngx](https://docs.paperless-ngx.com) 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...]
```

```console
$ 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:

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

```bash
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`](https://www.passwordstore.org/) 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:

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

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

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

## Tests

```bash
./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.