docspell cli

This is a command line interface to Docspell, a personal document management system.

The CLI is developed independently with the docspell server. Commands support the current (at the time of writing) version of docspell. When the server upgrades its api, the cli is adopted accordingly.

This CLI is meant to be used by humans and other programs. The default output format is tabular which prints a table to stdout. This same table can be formatted to CSV by using the format option csv. These two formats may omit some details from the server responses for readability reasons. When using this cli from other programs, or when you're looking for some detail, the formats json and lisp are recommended. They contain every detail in a well structured form.

State

This CLI is beta … probably forever. I'm using it a lot and hope that it will be improved over time.

The goal is to eventually have all the REST endpoints covered here, or at least those that are frequently used.

Usage

There are binaries provided at the release page that you can download. Or you can build it as described below.

Run dsc help to see a command overview and global options. These options apply to (almost) all commands. Additionally, each command has its own set of options and arguments. A command has its help available via dsc [subcommand] --help.

Config File

The config file is read from the OS defined location, or it can be specfified explicitly either via an environment variable DSC_CONFIG or as an option. You can run dsc write-config-file to create a default config file in the standard location. The default location on linux systems is ~/.config/dsc/config.toml.

The config file looks like this (also, look in the ci/ folder for another and always up to date example):

docspell_url = "http://localhost:7880"
default_format = "Tabular"
# admin_secret = "test123"
# default_source_id = "<some sorce id>"
# pass_entry = "my/pass/entry"
# pass_otp_secret = "key:totp" #or "my/pass/totp_entry"
# default_account = "demo"
pdf_viewer = ["zathura", "{}"]
# proxy = myproxy.com
# proxy_user = me
# proxy_password = superword
# extra_certificate = /path/to/trust.pem #PEM or DER
# accept_invalid_certificates = false

The pdf_viewer is used with the view command to display the PDF file. It must be a list where the first element is the program to run and subsequent elements are its arguments. For each argument, any {} is replaced by the path to the file.

Authentication

The login command can be used to initially login to docspell server.

It accepts a username and password. It also supports the pass password manager. The user name can be fixed in the config file as well as the entry to use with pass. This means you can then just run dsc login without any arguments. The retrieved session token is stored on your file system next to the config file. Subsequent commands can use the session token. Once it is expired, you need to call dsc login again.

When TOTP is enabled, it is also possible to store the secret in pass and specify the entry to this in the config file at pass_otp_secret. Dsc can then calculate the otp accordingly. If the value starts with key: then the renaming part is used to lookup such a line in the main entry (defined via pass_entry). If not prefixed with key: a separate pass entry is looked up.

For commands file-exists and upload it is possible to use a source id or the integration endpoint instead of being authenticated.

Building

Install nix and run nix-shell or nix develop in the source root. This installs required rust tools. Alternatively, the rust tool chain can be setup with rustup. Currently, dsc requires rust >= 1.54.0.

Building the binary for your platform (The second line strips the binary of debug symbols):

> cargo build --release
> strip target/release/dsc

This requires the openssl libraries installed on your system.

To build against a statically linked rustls library instead, use:

> cargo build --release --no-default-features --features rustls

To include a statically linked openssl, build it via:

> cargo build --release --no-default-features --features vendored-openssl

Shell Integration

The library for parsing command line arguments has a nice feature that generates completions for various shells. This has been build into the dsc tool. For example, in order to have completions in fish, run:

$ dsc generate-completions --shell fish | source

… and enjoy tab completion 😉

Run dsc generate-completions --help to see what other shells are supported.

Nix Package

The nix/dsc.nix contains a nix expression to build this package. It can be build using flake enabled nix:

nix build

Or ran as

nix run github:docspell/dsc

The repository provides a package which can be included in your system flake by adding:

{
  inputs.dsc-flake.url = "github:docspell/dsc";
  ...
  outputs =
  ...
    environment.systemPackages = [ dsc-flake.packages.${system}.default ]
  ...
}

And a module for dsc watch. An example of its usage is in nixosConfigurations output of the flake.

Examples

Reset the password of an account:

> dsc admin reset-password user32
┌─────────┬──────────────┬──────────────────┐
│ success │ new password │ message          │
│ true    │ 9rRVrhq19jz  │ Password updated │
└─────────┴──────────────┴──────────────────┘

Recreate the full text index:

> dsc admin recreate-index
┌─────────┬─────────────────────────────────────┐
│ success │ message                             │
│ true    │ Full-text index will be re-created. │
└─────────┴─────────────────────────────────────┘

Search some documents:

> dsc search 'date>2020-08-01 corr:acme*'
┌──────────┬─────────────────────────┬───────────┬────────────┬─────┬───────────────┬─────────────┬────────┬──────────────────────────────┬────────┐
│ id       │ name                    │ state     │ date       │ due │ correspondent │ concerning  │ folder │ tags                         │ fields │
│ 7xoiE4Xd │ DOC-20191223-155729.jpg │ created   │ 2020-09-08 │     │ Acme          │             │        │ Invoice                      │        │
│ BV2po65m │ DOC-20200808-154204.jpg │ confirmed │ 2020-08-08 │     │ Acme          │             │        │ Receipt, Tax                 │        │
│ 8GA2ewgE │ DOC-20200807-115654.jpg │ created   │ 2020-08-07 │     │ Acme          │             │        │ Paper, Receipt               │        │
│ FTUnhZ3A │ DOC-20200804-132305.jpg │ confirmed │ 2020-08-04 │     │ Acme          │             │        │ Receipt, Tax                 │        │
│ 6MKV6SEQ │ DOC-20191223-155707.jpg │ confirmed │ 2020-08-03 │     │ Acme          │ Derek Jeter │        │ Important, Information, Todo │        │
└──────────┴─────────────────────────┴───────────┴────────────┴─────┴───────────────┴─────────────┴────────┴──────────────────────────────┴────────┘

Use JSON:

> dsc -f json search 'date>2020-08-01 corr:acme*' | jq | head -n20
{
  "groups": [
    {
      "name": "2020-09",
      "items": [
        {
          "id": "7xoiE4XdwgD-FTGjD91MptP-yrnKpLrJTfg-Eb2S3BCSd38",
          "name": "DOC-20191223-155729.jpg",
          "state": "created",
          "date": 1599566400000,
          "due_date": null,
          "source": "android",
          "direction": "incoming",
          "corr_org": {
            "id": "GDceAkgrk8m-kjBWUmcuLTV-Zrzp85ByXpX-hq5SS4Yp3Pg",
            "name": "Acme"
          },
          "corr_person": null,
          "conc_person": null,
          "conc_equip": null,

Upload some files:

> dsc up README.*
File already in Docspell: README.md
Adding to request: README.txt
Sending request …
┌─────────┬──────────────────┐
│ success │ message          │
├─────────┼──────────────────┤
│ true    │ Files submitted. │
└─────────┴──────────────────┘

Making a release

1. Set version in Cargo.toml
2. Run cargo update to update Cargo.lock
3. Run nix-build and fix hashes
4. Commit + Tag
5. push tag to github

The release is being built by github actions as well as the docker images.