mirror of
https://github.com/TheAnachronism/docspell.git
synced 2025-06-22 02:18:26 +00:00
Add documentation for the cli tool
This commit is contained in:
eikek
@ -4,7 +4,7 @@ description = "There are several tools distributed with docspell, like a program
|
||||
weight = 60
|
||||
insert_anchor_links = "right"
|
||||
template = "pages.html"
|
||||
redirect_to = "docs/tools/ds"
|
||||
redirect_to = "docs/tools/cli/"
|
||||
sort_by = "weight"
|
||||
[extra]
|
||||
mktoc = false
|
||||
|
||||
@ -13,10 +13,10 @@ firefox.
|
||||
Installation is a bit complicated, since you need to install external
|
||||
tools and the web extension. Both work together.
|
||||
|
||||
# Install `ds.sh`
|
||||
# Install `dsc`
|
||||
|
||||
First copy the `ds.sh` tool somewhere in your `PATH`, maybe
|
||||
`/usr/local/bin` as described above.
|
||||
First copy the [dsc](@/docs/tools/cli.md) tool somewhere in your
|
||||
`PATH`, maybe `/usr/local/bin`.
|
||||
|
||||
|
||||
# Install the native part
|
||||
@ -44,10 +44,14 @@ for details.
|
||||
And you might want to modify this json file, so the path to the
|
||||
`native.py` script is correct (it must be absolute).
|
||||
|
||||
If the `ds.sh` script is in your `$PATH`, then this should
|
||||
work. Otherwise, edit the `native.py` script and change the path to
|
||||
the tool. Or create a file `$HOME/.config/docspell/ds.cmd` whose
|
||||
content is the path to the `ds.sh` script.
|
||||
If the `dsc` tool is in your `$PATH`, then this should work. You need
|
||||
to provide a default source id in your `~/.config/dsc/config.toml` so
|
||||
that the upload command can be used without further arguments.
|
||||
|
||||
Otherwise, edit the `native.py` script and change the path to the tool
|
||||
and/or the arguments. Or create a file
|
||||
`$HOME/.config/docspell/dsc.cmd` whose content is the path to the
|
||||
`dsc` tool.
|
||||
|
||||
|
||||
# Install the extension
|
||||
@ -73,7 +77,7 @@ alternatives:
|
||||
When you right click on a file link, there should be a context menu
|
||||
entry *'Docspell Upload Helper'*. The add-on will download this file
|
||||
using the browser and then send the file path to the `native.py`
|
||||
script. This script will in turn call `ds.sh` which finally uploads it
|
||||
script. This script will in turn call `dsc` which finally uploads it
|
||||
to your configured URLs.
|
||||
|
||||
Open the Add-ons page (`Ctrl`+`Shift`+`A`), the new add-on should be
|
||||
|
||||
266
website/site/content/docs/tools/cli.md
Normal file
266
website/site/content/docs/tools/cli.md
Normal file
@ -0,0 +1,266 @@
|
||||
+++
|
||||
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.
|
||||
@ -1,9 +1,15 @@
|
||||
+++
|
||||
title = "Directory Cleaner"
|
||||
title = "Directory Cleaner (⊗)"
|
||||
description = "Clean directories from files in docspell"
|
||||
weight = 32
|
||||
weight = 150
|
||||
+++
|
||||
|
||||
{% infobubble(mode="info", title="⚠ Please note") %}
|
||||
This script is now obsolete, you can use the [**CLI tool**](../cli/) instead.
|
||||
|
||||
Use the `cleanup` or the `upload` command.
|
||||
{% end %}
|
||||
|
||||
# Introduction
|
||||
|
||||
This script is made for cleaning up the consumption directory used for
|
||||
|
||||
@ -1,9 +1,16 @@
|
||||
+++
|
||||
title = "Consume Directory"
|
||||
title = "Consume Directory (⊗)"
|
||||
description = "A script to watch a directory for new files and upload them to docspell."
|
||||
weight = 30
|
||||
weight = 110
|
||||
+++
|
||||
|
||||
|
||||
{% infobubble(mode="info", title="⚠ Please note") %}
|
||||
This script is now obsolete, you can use the [**CLI tool**](../cli/) instead.
|
||||
|
||||
You can use the `watch` command, or the `upload` command with `--poll`.
|
||||
{% end %}
|
||||
|
||||
# Introduction
|
||||
|
||||
The `consumerdir.sh` is a bash script that works in two modes:
|
||||
|
||||
@ -1,9 +1,17 @@
|
||||
+++
|
||||
title = "Convert All PDFs"
|
||||
title = "Convert All PDFs (⊗)"
|
||||
description = "Convert all PDF files using OcrMyPdf."
|
||||
weight = 60
|
||||
weight = 160
|
||||
+++
|
||||
|
||||
{% infobubble(mode="info", title="⚠ Please note") %}
|
||||
This script is now obsolete, you can use the [**CLI tool**](../cli/) instead.
|
||||
|
||||
Use the `convert-all-pdfs` admin command, e.g. `dsc admin
|
||||
convert-all-pdfs`.
|
||||
{% end %}
|
||||
|
||||
|
||||
# convert-all-pdf.sh
|
||||
|
||||
With version 0.9.0 there was support added for another external tool,
|
||||
|
||||
@ -1,9 +1,16 @@
|
||||
+++
|
||||
title = "Upload CLI"
|
||||
title = "Upload CLI (⊗)"
|
||||
description = "A script to quickly upload files from the command line."
|
||||
weight = 10
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
|
||||
{% infobubble(mode="info", title="⚠ Please note") %}
|
||||
This script is now obsolete, you can use the [**CLI tool**](../cli/) instead.
|
||||
|
||||
Use the `upload` command (or the `up` alias), like `dsc up *.pdf`.
|
||||
{% end %}
|
||||
|
||||
# Introduction
|
||||
|
||||
The `tools/ds.sh` is a bash script to quickly upload files from the
|
||||
|
||||
@ -1,9 +1,15 @@
|
||||
+++
|
||||
title = "Regenerate Preview Images"
|
||||
title = "Regenerate Preview Images (⊗)"
|
||||
description = "Re-generates all preview images."
|
||||
weight = 80
|
||||
weight = 130
|
||||
+++
|
||||
|
||||
{% infobubble(mode="info", title="⚠ Please note") %}
|
||||
This script is now obsolete, you can use the [**CLI tool**](../cli/) instead.
|
||||
|
||||
Use the `generate-previews` admin command, e.g. `dsc admin generate-previews`.
|
||||
{% end %}
|
||||
|
||||
# regenerate-previews.sh
|
||||
|
||||
This is a simple bash script to trigger the endpoint that submits task
|
||||
|
||||
@ -1,9 +1,17 @@
|
||||
+++
|
||||
title = "Reset Password"
|
||||
title = "Reset Password (⊗)"
|
||||
description = "Resets a user password."
|
||||
weight = 70
|
||||
weight = 120
|
||||
+++
|
||||
|
||||
{% infobubble(mode="info", title="⚠ Please note") %}
|
||||
This script is now obsolete, you can use the [**CLI tool**](../cli/) instead.
|
||||
|
||||
Use the `reset-password` admin command, e.g. `dsc admin reset-password
|
||||
--account "smith/john"`, where `smith` is the collective id and `john`
|
||||
the username.
|
||||
{% end %}
|
||||
|
||||
|
||||
This script can be used to reset a user password. This can be done by
|
||||
admins, who know the `admin-endpoint.secret` value in the
|
||||
|
||||
Reference in New Issue
Block a user