Translate and expand README

README.md

@@ -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:
+- Scan one or more configured import directories.
-- Überprüft Dateien in konfigurierten Import-Verzeichnissen
+- Check every file with `dsc file-exists` to see whether it is already known to Docspell.
-- Prüft für jede Datei, ob sie bereits in Docspell existiert
+- Move files that already exist in Docspell and are in the `confirmed` state into a local archive.
-- Wenn die Datei existiert und bestätigt ist:
+- Preserve useful archive structure by Docspell folder and item date.
-  - Verschiebt sie in ein Archiv-Verzeichnis
+- Optionally upload files that do not yet exist in Docspell.
-  - Organisiert sie nach Datum und Ordnerstruktur
+- Mount Docspell search results as a read-only filesystem.
-- Optional: Lädt noch nicht existierende Dateien automatisch nach Docspell hoch
+- 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/)
+- [Docspell Command Line Client (`dsc`)](https://docspell.org/docs/tools/cli/) for the import/archive command.
-- `jq` Kommandozeilentool
+- A running Docspell instance.
-- Eine Konfigurationsdatei unter `~/docspell-cli.json`
+- 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.
+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.
-It uses the same `~/docspell-cli.json` configuration and password command as the import 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.
+The mount also includes:
-- `--limit`: number of items fetched per API request, default `1000`.
-- `--auth-header`: token header, default `X-Docspell-Auth`.
 
-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
+```