{"id":13687836,"url":"https://github.com/docspell/dsc","last_synced_at":"2025-05-01T15:33:10.399Z","repository":{"id":36967655,"uuid":"382872450","full_name":"docspell/dsc","owner":"docspell","description":"Docpell command line interface","archived":false,"fork":false,"pushed_at":"2024-04-09T19:44:08.000Z","size":1088,"stargazers_count":18,"open_issues_count":17,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-10T04:07:02.016Z","etag":null,"topics":["cli","docspell","rust"],"latest_commit_sha":null,"homepage":"https://docspell.org/docs/tools/cli","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docspell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-07-04T14:30:01.000Z","updated_at":"2024-04-15T01:29:57.559Z","dependencies_parsed_at":"2024-02-08T18:32:36.459Z","dependency_job_id":"f825c0db-a024-42c2-a24a-d01ed2b7ba92","html_url":"https://github.com/docspell/dsc","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docspell%2Fdsc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docspell%2Fdsc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docspell%2Fdsc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docspell%2Fdsc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docspell","download_url":"https://codeload.github.com/docspell/dsc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224266318,"owners_count":17283105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docspell","rust"],"created_at":"2024-08-02T15:01:01.540Z","updated_at":"2025-05-01T15:33:10.394Z","avatar_url":"https://github.com/docspell.png","language":"Rust","funding_links":[],"categories":["cli"],"sub_categories":[],"readme":"[![Integration-Tests](https://github.com/docspell/dsc/actions/workflows/int_test.yml/badge.svg)](https://github.com/docspell/dsc/actions/workflows/int_test.yml)\n[![License](https://img.shields.io/github/license/docspell/dsc.svg?style=flat\u0026color=steelblue)](https://github.com/docspell/dsc/blob/master/LICENSE.txt)\n[![Chat](https://img.shields.io/gitter/room/eikek/docspell?style=flat\u0026color=steelblue\u0026logo=gitter)](https://gitter.im/eikek/docspell)\n[![Docker Pulls](https://img.shields.io/docker/pulls/docspell/dsc?color=steelblue\u0026style=flat\u0026logo=docker)](https://hub.docker.com/u/docspell/dsc)\n\n# docspell cli\n\nThis is a command line interface to Docspell, a personal document\nmanagement system.\n\nThe CLI is developed independently with the docspell server. Commands\nsupport the current (at the time of writing) version of docspell. When\nthe server upgrades its api, the cli is adopted accordingly.\n\nThis CLI is meant to be used by humans and other programs. The default\noutput format is `tabular` which prints a table to stdout. This same\ntable can be formatted to CSV by using the format option `csv`. These\ntwo formats may omit some details from the server responses for\nreadability reasons. When using this cli from other programs, or when\nyou're looking for some detail, the formats `json` and `lisp` are\nrecommended. They contain every detail in a well structured form.\n\n## State\n\nThis CLI is beta … probably forever. I'm using it a lot and hope that\nit will be improved over time.\n\nThe goal is to eventually have all the [REST\nendpoints](https://docspell.org/openapi/docspell-openapi.html) covered\nhere, or at least those that are frequently used.\n\n## Usage\n\nThere are binaries provided at the [release\npage](https://github.com/docspell/dsc/releases/latest) that you can\ndownload. Or you can build it as described below.\n\nRun `dsc help` to see a command overview and global options. These\noptions apply to (almost) all commands. Additionally, each command has\nits own set of options and arguments. A command has its help available\nvia `dsc [subcommand] --help`.\n\n\n## Config File\n\nThe config file is read from the OS defined location, or it can be\nspecfified explicitly either via an environment variable `DSC_CONFIG`\nor as an option. You can run `dsc write-config-file` to create a\ndefault config file in the standard location. The default location on\nlinux systems is `~/.config/dsc/config.toml`.\n\nThe config file looks like this (also, look in the `ci/` folder for\nanother and always up to date example):\n\n``` toml\ndocspell_url = \"http://localhost:7880\"\ndefault_format = \"Tabular\"\n# admin_secret = \"test123\"\n# default_source_id = \"\u003csome sorce id\u003e\"\n# pass_entry = \"my/pass/entry\"\n# pass_otp_secret = \"key:totp\" #or \"my/pass/totp_entry\"\n# default_account = \"demo\"\npdf_viewer = [\"zathura\", \"{}\"]\n# proxy = myproxy.com\n# proxy_user = me\n# proxy_password = superword\n# extra_certificate = /path/to/trust.pem #PEM or DER\n# accept_invalid_certificates = false\n```\n\nThe `pdf_viewer` is used with the `view` command to display the PDF\nfile. It must be a list where the first element is the program to run\nand subsequent elements are its arguments. For each argument, any `{}`\nis replaced by the path to the file.\n\n\n## Authentication\n\nThe `login` command can be used to initially login to docspell server.\n\nIt accepts a username and password. It also supports the\n[pass](https://www.passwordstore.org/) password manager. The user name\ncan be fixed in the config file as well as the entry to use with\n[pass](https://www.passwordstore.org/). This means you can then just\nrun `dsc login` without any arguments. The retrieved session token is\nstored on your file system next to the config file. Subsequent\ncommands can use the session token. Once it is expired, you need to\ncall `dsc login` again.\n\nWhen TOTP is enabled, it is also possible to store the secret in\n[pass](https://www.passwordstore.org/) and specify the entry to this\nin the config file at `pass_otp_secret`. Dsc can then calculate the\notp accordingly. If the value starts with `key:` then the renaming\npart is used to lookup such a line in the main entry (defined via\n`pass_entry`). If not prefixed with `key:` a separate pass entry is\nlooked up.\n\nFor commands `file-exists` and `upload` it is possible to use a source\nid or the integration endpoint instead of being authenticated.\n\n\n## Building\n\nInstall [nix](https://nixos.org/download.html#nix-quick-install) and\nrun `nix-shell` or `nix develop` in the source root. This installs\nrequired rust tools. Alternatively, the rust tool chain can be setup\nwith [rustup](https://rustup.rs/). Currently, dsc requires rust \u003e=\n1.54.0.\n\nBuilding the binary for your platform (The second line strips the\nbinary of debug symbols):\n\n``` bash\n\u003e cargo build --release\n\u003e strip target/release/dsc\n```\n\nThis requires the openssl libraries installed on your system.\n\nTo build against a statically linked rustls library instead, use:\n``` bash\n\u003e cargo build --release --no-default-features --features rustls\n```\n\nTo include a statically linked openssl, build it via:\n``` bash\n\u003e cargo build --release --no-default-features --features vendored-openssl\n```\n\n\n## Shell Integration\n\nThe [library for parsing command line arguments](https://clap.rs/) has\na nice feature that generates completions for various shells. This has\nbeen build into the `dsc` tool. For example, in order to have\ncompletions in [fish](https://fishshell.com/), run:\n\n``` fish\n$ dsc generate-completions --shell fish | source\n```\n\n… and enjoy tab completion :wink:\n\nRun `dsc generate-completions --help` to see what other shells are\nsupported.\n\n\n## Nix Package\n\nThe `nix/dsc.nix` contains a nix expression to build this package. It\ncan be build using [flake enabled](https://nixos.wiki/wiki/Flakes) nix:\n\n``` bash\nnix build\n```\n\nOr ran as\n\n``` bash\nnix run github:docspell/dsc\n```\n\nThe repository provides a package which can be included in your system\nflake by adding:\n\n``` nix\n{\n  inputs.dsc-flake.url = \"github:docspell/dsc\";\n  ...\n  outputs =\n  ...\n    environment.systemPackages = [ dsc-flake.packages.${system}.default ]\n  ...\n}\n```\n\nAnd a module for dsc watch. An example of its usage is in nixosConfigurations\noutput of the flake.\n\n\n## Examples\n\nReset the password of an account:\n``` bash\n\u003e dsc admin reset-password user32\n┌─────────┬──────────────┬──────────────────┐\n│ success │ new password │ message          │\n│ true    │ 9rRVrhq19jz  │ Password updated │\n└─────────┴──────────────┴──────────────────┘\n```\n\n\nRecreate the full text index:\n``` bash\n\u003e dsc admin recreate-index\n┌─────────┬─────────────────────────────────────┐\n│ success │ message                             │\n│ true    │ Full-text index will be re-created. │\n└─────────┴─────────────────────────────────────┘\n```\n\nSearch some documents:\n``` bash\n\u003e dsc search 'date\u003e2020-08-01 corr:acme*'\n┌──────────┬─────────────────────────┬───────────┬────────────┬─────┬───────────────┬─────────────┬────────┬──────────────────────────────┬────────┐\n│ id       │ name                    │ state     │ date       │ due │ correspondent │ concerning  │ folder │ tags                         │ fields │\n│ 7xoiE4Xd │ DOC-20191223-155729.jpg │ created   │ 2020-09-08 │     │ Acme          │             │        │ Invoice                      │        │\n│ BV2po65m │ DOC-20200808-154204.jpg │ confirmed │ 2020-08-08 │     │ Acme          │             │        │ Receipt, Tax                 │        │\n│ 8GA2ewgE │ DOC-20200807-115654.jpg │ created   │ 2020-08-07 │     │ Acme          │             │        │ Paper, Receipt               │        │\n│ FTUnhZ3A │ DOC-20200804-132305.jpg │ confirmed │ 2020-08-04 │     │ Acme          │             │        │ Receipt, Tax                 │        │\n│ 6MKV6SEQ │ DOC-20191223-155707.jpg │ confirmed │ 2020-08-03 │     │ Acme          │ Derek Jeter │        │ Important, Information, Todo │        │\n└──────────┴─────────────────────────┴───────────┴────────────┴─────┴───────────────┴─────────────┴────────┴──────────────────────────────┴────────┘\n```\n\nUse JSON:\n``` bash\n\u003e dsc -f json search 'date\u003e2020-08-01 corr:acme*' | jq | head -n20\n{\n  \"groups\": [\n    {\n      \"name\": \"2020-09\",\n      \"items\": [\n        {\n          \"id\": \"7xoiE4XdwgD-FTGjD91MptP-yrnKpLrJTfg-Eb2S3BCSd38\",\n          \"name\": \"DOC-20191223-155729.jpg\",\n          \"state\": \"created\",\n          \"date\": 1599566400000,\n          \"due_date\": null,\n          \"source\": \"android\",\n          \"direction\": \"incoming\",\n          \"corr_org\": {\n            \"id\": \"GDceAkgrk8m-kjBWUmcuLTV-Zrzp85ByXpX-hq5SS4Yp3Pg\",\n            \"name\": \"Acme\"\n          },\n          \"corr_person\": null,\n          \"conc_person\": null,\n          \"conc_equip\": null,\n```\n\nUpload some files:\n``` bash\n\u003e dsc up README.*\nFile already in Docspell: README.md\nAdding to request: README.txt\nSending request …\n┌─────────┬──────────────────┐\n│ success │ message          │\n├─────────┼──────────────────┤\n│ true    │ Files submitted. │\n└─────────┴──────────────────┘\n```\n\n\n## Making a release\n\n1. Set version in `Cargo.toml`\n2. Run `cargo update` to update `Cargo.lock`\n3. Run `nix-build` and fix hashes\n4. Commit + Tag\n5. push tag to github\n\nThe release is being built by github actions as well as the docker\nimages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocspell%2Fdsc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocspell%2Fdsc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocspell%2Fdsc/lists"}