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.
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.
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.
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 = falseThe 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.
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.
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/dscThis 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 rustlsTo include a statically linked openssl, build it via:
> cargo build --release --no-default-features --features vendored-opensslThe 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.
The nix/dsc.nix contains a nix expression to build this package. It
can be build using flake enabled nix:
nix buildOr ran as
nix run github:docspell/dscThe 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.
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. β
βββββββββββ΄βββββββββββββββββββ- Set version in
Cargo.toml - Run
cargo updateto updateCargo.lock - Run
nix-buildand fix hashes - Commit + Tag
- push tag to github
The release is being built by github actions as well as the docker images.
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent