Translate and expand README
This commit is contained in:
Jan Bader
@@ -1,61 +1,151 @@
|
||||
# Docspell CLI
|
||||
|
||||
Ein Tool zum Aufräumen des Docspell-Importverzeichnisses und zum automatischen Archivieren von bestätigten Dokumenten.
|
||||
A small command-line helper for managing Docspell import folders, archiving files that have already been confirmed in Docspell, optionally uploading missing files, and exposing a Docspell collection as a read-only FUSE filesystem.
|
||||
|
||||
## Funktionsweise
|
||||
## Features
|
||||
|
||||
Das Programm:
|
||||
- Überprüft Dateien in konfigurierten Import-Verzeichnissen
|
||||
- Prüft für jede Datei, ob sie bereits in Docspell existiert
|
||||
- Wenn die Datei existiert und bestätigt ist:
|
||||
- Verschiebt sie in ein Archiv-Verzeichnis
|
||||
- Organisiert sie nach Datum und Ordnerstruktur
|
||||
- Optional: Lädt noch nicht existierende Dateien automatisch nach Docspell hoch
|
||||
- Scan one or more configured import directories.
|
||||
- Check every file with `dsc file-exists` to see whether it is already known to Docspell.
|
||||
- Move files that already exist in Docspell and are in the `confirmed` state into a local archive.
|
||||
- Preserve useful archive structure by Docspell folder and item date.
|
||||
- Optionally upload files that do not yet exist in Docspell.
|
||||
- Mount Docspell search results as a read-only filesystem.
|
||||
- Resolve Docspell item URLs/IDs to local mounted paths, and local mounted paths back to Docspell item URLs.
|
||||
|
||||
## Voraussetzungen
|
||||
## Requirements
|
||||
|
||||
- [Docspell Command Line Client (dsc)](https://docspell.org/docs/tools/cli/)
|
||||
- `jq` Kommandozeilentool
|
||||
- Eine Konfigurationsdatei unter `~/docspell-cli.json`
|
||||
- [Docspell Command Line Client (`dsc`)](https://docspell.org/docs/tools/cli/) for the import/archive command.
|
||||
- A running Docspell instance.
|
||||
- A password command, for example [`pass`](https://www.passwordstore.org/), that prints the Docspell password to stdout.
|
||||
- FUSE support for the `mount` command, including `fusermount` or `fusermount3` for unmounting.
|
||||
- A configuration file at `~/docspell-cli.json`.
|
||||
|
||||
## Konfiguration
|
||||
## Configuration
|
||||
|
||||
Erstellen Sie eine `docspell-cli.json` Datei in Ihrem Home-Verzeichnis: [Beispiel-Konfiguration](./docspell-cli-example.json)
|
||||
Create `~/docspell-cli.json`. See [docspell-cli-example.json](./docspell-cli-example.json) for a complete example.
|
||||
|
||||
```json
|
||||
{
|
||||
"passwordCommand": "pass",
|
||||
"passwordCommandArgs": ["show", "docspell/password"],
|
||||
"user": "admin@example.com",
|
||||
"docspellURL": "https://docspell.example.com",
|
||||
"mountPath": "/home/user/mnt/docspell",
|
||||
"mountQuery": "",
|
||||
"archiveDirectory": "/home/user/Documents/Archive",
|
||||
"importDirectories": [
|
||||
"/home/user/Documents/Inbox",
|
||||
"/home/user/Downloads/Scan"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Configuration fields:
|
||||
|
||||
- `passwordCommand`: executable used to retrieve the Docspell password.
|
||||
- `passwordCommandArgs`: arguments passed to `passwordCommand`.
|
||||
- `user`: Docspell user/account used for login.
|
||||
- `docspellURL`: base URL of the Docspell instance.
|
||||
- `mountPath`: default mount point for the FUSE filesystem and helper commands.
|
||||
- `mountQuery`: default Docspell item query exposed by the mount command.
|
||||
- `archiveDirectory`: destination root for confirmed imported files.
|
||||
- `importDirectories`: folders scanned by the import/archive command.
|
||||
|
||||
## Import and archive workflow
|
||||
|
||||
Run the default command without a subcommand:
|
||||
|
||||
```bash
|
||||
docspell-cli
|
||||
```
|
||||
|
||||
The command logs in with `dsc`, scans every configured import directory, and checks each file against Docspell.
|
||||
|
||||
If a file already exists in Docspell, the tool fetches the item details and prints the Docspell item URL. The local file is moved only when the Docspell item is `confirmed` and has an item date. Files that are still unconfirmed or missing a date are left untouched.
|
||||
|
||||
Confirmed files are archived under:
|
||||
|
||||
```text
|
||||
<archiveDirectory>/<Docspell folder>/<year>/<month>/<YYYYMMDD corresponding party - item name>.<original extension>
|
||||
```
|
||||
|
||||
If the Docspell item has no folder, `null` is used as the folder name. The corresponding party is taken from the corresponding organization first, then the corresponding person.
|
||||
|
||||
### Upload missing files
|
||||
|
||||
By default, files that do not exist in Docspell stay in place. Enable uploads with either the flag or environment variable:
|
||||
|
||||
```bash
|
||||
docspell-cli --upload-missing
|
||||
DS_CC_UPLOAD_MISSING=true docspell-cli
|
||||
```
|
||||
|
||||
Uploaded files are not archived immediately. They are re-checked on the next run, after Docspell has processed and confirmed them.
|
||||
|
||||
## Read-only FUSE mount
|
||||
|
||||
The `mount` subcommand exposes a Docspell collection as a read-only filesystem.
|
||||
It uses the same `~/docspell-cli.json` configuration and password command as the import command.
|
||||
The `mount` subcommand exposes Docspell search results as a read-only filesystem. It uses the same `~/docspell-cli.json` file and password command as the import/archive command.
|
||||
|
||||
Set `mountPath` in the config to define the default mount point and `mountQuery` to define the default Docspell query.
|
||||
|
||||
```bash
|
||||
mkdir -p ~/mnt/docspell
|
||||
docspell-cli mount ~/mnt/docspell # starts in the background
|
||||
|
||||
docspell-cli mount ~/mnt/docspell
|
||||
# or, with mountPath configured:
|
||||
docspell-cli mount
|
||||
|
||||
# unmount when done
|
||||
fusermount -u ~/mnt/docspell
|
||||
# or, depending on your system:
|
||||
fusermount3 -u ~/mnt/docspell
|
||||
```
|
||||
|
||||
Mounted files are grouped as:
|
||||
By default the command starts the mount process in the background. To run it in the foreground, set:
|
||||
|
||||
```bash
|
||||
DOCSPELL_CLI_MOUNT_FOREGROUND=1 docspell-cli mount ~/mnt/docspell
|
||||
```
|
||||
|
||||
Mounted files are grouped by Docspell folder and date:
|
||||
|
||||
```text
|
||||
<Docspell folder>/<year>/<month>/<attachment name>
|
||||
<Docspell folder>/<year>/<month>/<item name>.<attachment extension>
|
||||
```
|
||||
|
||||
Options:
|
||||
Items without a folder are placed below `No Folder`; items without a date are placed below `No Date`. Multiple attachments are named with a numeric suffix. File contents are downloaded lazily from Docspell when read.
|
||||
|
||||
- `--query`: Docspell item query to expose, defaults to `mountQuery` from config.
|
||||
- `--limit`: number of items fetched per API request, default `1000`.
|
||||
- `--auth-header`: token header, default `X-Docspell-Auth`.
|
||||
The mount also includes:
|
||||
|
||||
The mount is read-only. File contents are downloaded lazily from `/api/v1/sec/attachment/{id}` when read.
|
||||
- `by-id/<id-prefix>/<item-id>.<extension>` entries for stable ID-based lookups.
|
||||
- `.docspell-cli-metadata.json`, used by helper commands to map item IDs to friendly mounted paths.
|
||||
|
||||
Helper commands:
|
||||
Mount options:
|
||||
|
||||
- `--query`: Docspell item query to expose. Defaults to `mountQuery` from the config.
|
||||
- `--limit`: number of items fetched per API request. Defaults to `1000`.
|
||||
- `--auth-header`: HTTP header used for the Docspell auth token. Defaults to `X-Docspell-Auth`.
|
||||
|
||||
## Helper commands
|
||||
|
||||
Resolve a Docspell item ID or web URL to the local mounted path:
|
||||
|
||||
```bash
|
||||
docspell-cli get-local-path <item-id-or-web-url>
|
||||
```
|
||||
|
||||
`get-local-path` automatically starts the configured mount in the background if it is not mounted yet. If an existing mount is stale, the tool attempts to unmount it and start a fresh one.
|
||||
|
||||
Resolve a local mounted path, item ID, or item URL to the Docspell web URL:
|
||||
|
||||
```bash
|
||||
docspell-cli get-url <local-mounted-path-or-item-id>
|
||||
```
|
||||
|
||||
`get-local-path` starts the configured mount in the background if it is not mounted yet.
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
docspell-cli get-local-path https://docspell.example.com/app/item/abc123
|
||||
docspell-cli get-url ~/mnt/docspell/Invoices/2026/07/example.pdf
|
||||
docspell-cli get-url abc123
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user