mirror of
https://github.com/TheAnachronism/docspell.git
synced 2025-06-08 15:59:51 +00:00
267 lines
12 KiB
Markdown
267 lines
12 KiB
Markdown
+++
|
||
title = "CLI"
|
||
description = "A command line interface to."
|
||
weight = 5
|
||
+++
|
||
|
||
# Introduction
|
||
|
||
The **d**oc**s**pell **c**lient, short
|
||
[dsc](https://github.com/docspell/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](@/docs/api/_index.md) will be covered.
|
||
|
||
# Usage
|
||
|
||
Download the binary for your architecture from the [release
|
||
page](https://github.com/docspell/dsc/releases/latest) 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](https://hub.docker.com/repository/docker/docspell/dsc),
|
||
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](https://github.com/docspell/dsc) 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:
|
||
|
||
``` toml
|
||
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](https://passwordstore.org) 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](https://stedolan.github.io/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](@/docs/webapp/uploading.md#anonymous-upload) or via the
|
||
[integration endpoint](@/docs/api/upload.md#integration-endpoint).
|
||
|
||
A source id can be given in the config file, then there are no
|
||
additional options required. The simplest form is this:
|
||
|
||
``` shell
|
||
❯ 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](https://docs.rs/glob/0.3.0/glob/struct.Pattern.html).
|
||
|
||
``` shell
|
||
❯ 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.
|
||
|
||
``` shell
|
||
❯ 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](@/docs/configure/_index.md#admin-endpoint) either in the
|
||
config file or as an argument.
|
||
|
||
Reset user password:
|
||
``` shell
|
||
❯ dsc admin reset-password --account demo
|
||
┌─────────┬──────────────┬──────────────────┐
|
||
│ success │ new password │ message │
|
||
├─────────┼──────────────┼──────────────────┤
|
||
│ true │ 2q2UeCVvMYg │ Password updated │
|
||
└─────────┴──────────────┴──────────────────┘
|
||
```
|
||
|
||
Recreate fulltext index:
|
||
``` shell
|
||
❯ 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](@/docs/query/_index.md) and
|
||
prints the results.
|
||
|
||
``` shell
|
||
❯ 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:
|
||
``` shell
|
||
❯ 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](@/docs/api/upload.md#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`:
|
||
|
||
``` bash
|
||
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.
|