docspell-cli/README.md

# Docspell CLI

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.

## Features

- Scan one or more configured import directories.
- Check every file with Docspell's API 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.

## Requirements

- 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 `${XDG_CONFIG_HOME:-~/.config}/docspell-cli/config.json`.

## Configuration

Create `${XDG_CONFIG_HOME:-~/.config}/docspell-cli/config.json`. See [docspell-cli-example.json](./docspell-cli-example.json) for a complete example.

```bash
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/docspell-cli"
cp docspell-cli-example.json "${XDG_CONFIG_HOME:-$HOME/.config}/docspell-cli/config.json"
```

```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 `import` subcommand:

```bash
docspell-cli import
```

The command logs in to Docspell via the REST API, scans every configured import directory, and checks each file against Docspell by SHA-256 checksum.

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 import --upload-missing
DS_CC_UPLOAD_MISSING=true docspell-cli import
```

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 Docspell search results as a read-only filesystem. It uses the same XDG config 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
# or, with mountPath configured:
docspell-cli mount

# unmount when done
fusermount -u ~/mnt/docspell
# or, depending on your system:
fusermount3 -u ~/mnt/docspell
```

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>/<item name>.<attachment extension>
```

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.

The mount also includes:

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

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-path <item-id-or-web-url>
```

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

Examples:

```bash
docspell-cli get-path https://docspell.example.com/app/item/abc123
docspell-cli get-url ~/mnt/docspell/Invoices/2026/07/example.pdf
docspell-cli get-url abc123
```