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

Requirements

Docspell Command Line Client (dsc) for the import/archive command.
A running Docspell instance.
A password command, for example pass, 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.

Configuration

Create ~/docspell-cli.json. See docspell-cli-example.json for a complete example.

{
  "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:

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:

<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:

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

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:

DOCSPELL_CLI_MOUNT_FOREGROUND=1 docspell-cli mount ~/mnt/docspell

Mounted files are grouped by Docspell folder and date:

<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:

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:

docspell-cli get-url <local-mounted-path-or-item-id>

Examples:

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