12 KiB
+++ title = "CLI" description = "A command line interface to." weight = 5 +++
Introduction
The docspell client, short dsc, is a tool to use docspell through the command line. It is also aims to be useful for your own scripts and programs.
It is supposed to replace most of the shell scripts from the tools/
directory.
It is a work in progress; eventually most of the api will be covered.
Usage
Download the binary for your architecture from the release
page and rename it
to dsc. Then run dsc help to see an overview of all commands. The
help of each command is available via dsc help [command] or dsc [command] --help.
There are docker images at dockerhub, but it's usually easier to just download the binary. They should work on most systems without additional setups.
Below are some quick infos to get started, please see the project page for more info.
Configuration
A configuration file can be used to have some predefined settings, for example the docspell url, the admin secret etc. They can be overriden by specifying them as options.
The config looks like this:
docspell_url = "http://localhost:7880"
default_format = "Tabular"
admin_secret = "admin123"
default_account = "demo"
pdf_viewer = ["zathura", "{}"]
#pass_entry = "my/entry"
For linuxes, the default location is ~/.config/dsc/config.toml. You
can give a config file explicitly via an option or the environment
variable DSC_CONFIG.
If you use the pass password manager, you can add your password entry to the config file as well.
Output format
The "output format" defines how the information is printed on screen.
The default output format is Tabular which prints a simple table.
This table can also be formatted as CSV using csv as output format.
These two modes are intended for humans and they may not present all
information available.
Alternatively, there is json and lisp as output format. These are
intended for machine consumption. They always contain all information.
If you look for some detail, use for example json to get all data in
a structured form. On the shell you can use the awesome tool
jq to get exactly what you want.
Login
Many tasks require to be logged in. This can be done via the login
subcommand. You can specify account and password or fallback to the
values in the config file.
Once logged in, the session token will be saved to the filesystem
(next to the config file) and is used for subsequent commands. It is
renewed if expiry is near. If you don't issue any commands for a while
you need to login again.
Use Cases / Examples
Uploads files
The upload subcommand can uploads files to docspell. This is the
replacement for the ds.sh shell script.
You can specify a list of files that are all being uploaded. This command doesn't require to be logged in, it can also upload via a source id or via the integration endpoint.
A source id can be given in the config file, then there are no additional options required. The simplest form is this:
❯ dsc upload *.pdf
File already in Docspell: article-velo.pdf
Adding to request: test-ocr.pdf
Sending request …
┌─────────┬──────────────────┐
│ success │ message │
├─────────┼──────────────────┤
│ true │ Files submitted. │
└─────────┴──────────────────┘
By default, duplicate files are detected and not uploaded. This
uploads all files in one single request. By default, each file results
in one item. Using --single-item all files can be put into one item.
It is possible to specify certain metadata, like tags or a folder, that is then attached to the resulting item.
Upload by traversing a directory
The above use case was about uploading files. Using the upload
subcommand with the --traverse option, you can traverse directories
and upload all files in them. In this mode, each file will be uploaded
in a separate request, so the --single-item option cannot be used.
There are options to exclude/include files based on a glob pattern.
❯ dsc upload --traverse .
File already in Docspell: article-velo.pdf
File already in Docspell: demo/dirc/scan.21-03-12.15-50-54.pdf
File already in Docspell: demo/dirc/test-stamp.pdf
File already in Docspell: demo/letter-de.pdf
Uploading eike/keywords.pdf
File already in Docspell: eike/large-file.pdf
Uploading eike/letter-en.pdf
File already in Docspell: test-ocr.pdf
┌─────────┬────────────┐
│ success │ message │
├─────────┼────────────┤
│ true │ Uploaded 2 │
└─────────┴────────────┘
Watch a directory
The watch subcommand can be used to watch one or more directories
and upload files when they arrive. It uses the upload command under
the hood and therefore most options are also available here.
It detects file creations and skips a rename within a watched folder.
The flag -r or --recursive is required to recursively watch a
directory.
❯ dsc watch -r .
Watching directory (Recursive): .
Press Ctrl-C to quit.
------------------------------------------------------------------------------
Got: /home/eike/workspace/projects/dsc/local/files/./demo/letter-de.pdf
Adding to request: /home/eike/workspace/projects/dsc/local/files/./demo/letter-de.pdf
Sending request …
Server: Files submitted.
The --matches option allows to define a pattern for files to include.
If watching a directory is not possible due to system constraints
(e.g. when using NFS or SAMBA shares), a less efficient option is to
use the upload subcommand with --poll option which periodically
traverses a directory.
Admin commands
These are a set of commands that simply call a route at the server to submit a maintenance task or to reset the password of some user. These commands require the admin secret either in the config file or as an argument.
Reset user password:
❯ dsc admin reset-password --account demo
┌─────────┬──────────────┬──────────────────┐
│ success │ new password │ message │
├─────────┼──────────────┼──────────────────┤
│ true │ 2q2UeCVvMYg │ Password updated │
└─────────┴──────────────┴──────────────────┘
Recreate fulltext index:
❯ dsc admin --admin-secret admin123 recreate-index
┌─────────┬─────────────────────────────────────┐
│ success │ message │
├─────────┼─────────────────────────────────────┤
│ true │ Full-text index will be re-created. │
└─────────┴─────────────────────────────────────┘
Search for items
The search command takes a query and
prints the results.
❯ dsc search 'corr:*'
┌──────────┬────────────────────────────┬───────────┬────────────┬─────┬───────────────────────────┬───────────────┬────────┬─────────────┬────────────┬───────┐
│ id │ name │ state │ date │ due │ correspondent │ concerning │ folder │ tags │ fields │ files │
├──────────┼────────────────────────────┼───────────┼────────────┼─────┼───────────────────────────┼───────────────┼────────┼─────────────┼────────────┼───────┤
│ HVK7JuCF │ test-ocr.pdf │ created │ 2021-07-18 │ │ Pancake Company │ │ │ Certificate │ │ 1 │
│ 3odNawKE │ letter-en.pdf │ confirmed │ 2021-07-18 │ │ Pancake Company │ │ │ invoice │ │ 1 │
│ 3MA5NdhS │ large-file.pdf │ confirmed │ 2021-07-18 │ │ Axa │ │ │ Certificate │ │ 1 │
│ HDumXkRm │ keywords.pdf │ confirmed │ 2021-07-18 │ │ Pancake Company │ │ │ invoice │ │ 1 │
│ 733gM656 │ test-stamp.pdf │ created │ 2021-07-18 │ │ Pancake Company │ │ │ Contract │ │ 1 │
│ 8LiciitB │ scan.21-03-12.15-50-54.pdf │ confirmed │ 2021-07-18 │ │ Supermarket │ │ │ Receipt │ CHF 89.44 │ 1 │
│ 8nFt2z7T │ article-velo.pdf │ confirmed │ 2021-07-18 │ │ Supermarket/Rudolf Müller │ Rudolf Müller │ │ invoice │ CHF 123.11 │ 1 │
│ kfugGdXU │ letter-de.pdf │ created │ 2021-07-18 │ │ Axa │ Rudolf Müller │ │ invoice │ │ 1 │
└──────────┴────────────────────────────┴───────────┴────────────┴─────┴───────────────────────────┴───────────────┴────────┴─────────────┴────────────┴───────┘
The same can be formatted as json and, for example, only print the ids:
❯ dsc -f json search 'corr:*' | jq '.groups[].items[].id'
"HVK7JuCFt4W-qxkcwq1cWCV-dvpGo4DpZzU-Q16Xoujojas"
"3odNawKE1Ek-YJrWfPzekAq-47cjt14sexd-GK35JAEAanx"
"3MA5NdhSrbx-3JkjEpqHiyU-XyVNb15tioh-SUVjMLi1aoV"
"HDumXkRmDea-dNryjtRjk3V-ysdJmJNQGQS-UFb4DWNZJ3F"
"733gM656S4T-d4HmEgdAV6Z-9zuHAd3biKM-mBwNriZpqMB"
"8LiciitBVTi-DTmgiEUdqAJ-xXPckMvFHMc-JSiJMYvLaWh"
"8nFt2z7T9go-1qaCTTgodub-592n6gpmdNR-VRcyYAyT7qj"
"kfugGdXUGUc-mReaUnJxyUL-R44Lf7yH6RK-2JbZ1bv7dw"
Docker
The provided docker-compose setup runs this script to watch a single
directory, ./docs in current directory, for new files. If a new file
is detected, it is pushed to docspell.
This utilizes the integration
endpoint, which is enabled
in the config file, to allow uploading documents for all collectives.
A subfolder must be created for each registered collective. The docker
containers are configured to use http-header protection for the
integration endpoint. This requires you to provide a secret, that is
shared between the rest-server and the dsc tool. This can be done by
defining an environment variable which gets picked up by the
containers defined in docker-compose.yml:
export DOCSPELL_HEADER_VALUE="my-secret"
docker-compose up
Now you can create a folder ./docs/<collective-name> and place all
files in there that you want to import. Once dropped in this folder
the consumedir container will push it to docspell.