1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
# 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`.
## 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.
|
