===============
paperwork-shell
===============

--------------------------
cli interface to paperwork
--------------------------

:Author: Thomas Perret, 2019
:Version: 1.3.0
:Copyright: GPL-3.0+
:Manual section: 1
:Manual group: User commands

SYNOPSIS
========
paperwork-shell command

DESCRIPTION
===========

Paperwork shell is a cli interface to control paperwork working directory.
Most commands output a JSON structure.

COMMANDS
========
-h, --help    Show help for paperwork-shell

-q            Quiet mode (JSON reply only)

-b            Batch mode (never ask any question)

**help** [`command`]
 Show help for `command` or all commands by default

**scan**
 Start paperwork and immediately scan a page

**add_label** `document` `label` [`color`]
 Add a `label` on a `document`. `Color` must be specified if the `label`
 doesn't exists yet. `Color` will be ignored if the `label` already exists.
 `Color` format must be given in hexadecimal format (e.g. #abcdef).
 `Document` must be specified using the ID of the document (see **search**
 command).

**delete_doc** `document`    `document` must be specified using its ID (see **search** command)

**dump** `document` [`page`]
 Dump the content of the specified `document`.
 You can specify which `page` to dump with its number. Beware, `page` start from
 1. `Document` must be specified using its ID (see **search** command). Beware:
 This is the only command not replying in JSON format

**export_all** `output_dir` [-- [`--quality` *quality*] [`--page_format` *format*]]
 Export all documents as PDF files in `output_fir` folder. Default `quality` is
 50. Default page `format` is A4.

**export_doc** `document` `filename` [-- [`--quality quality`] [`--page_format format`]]
 Export one `document` as a PDF file named `filename`. Default `quality` is
 50. Default page `format` is A4.

**guess_labels** `document` [-- [`--apply`]]
 Guess the labels that should be set on the `document`. Guessed labels are not
 applied by default, if you wan them to be applied, invoke with the `--apply`
 argument. `Document` must be specified using its ID.

**import** `file_or_folder` [`file_or_folder` [...]] [-- [`--no_ocr`] [`--no_label_guessing`] [`--append document`]]
 Import a `file` or a PDF `folder`. OCR is run by default on images and on PDF
 pages without text (PDF containing only images) (use `--no_ocr` to disable).
 You can disable automatic label guessing by using `--no_label_guessing` option.
 You can add the file to an existing `document` by using the `--append` option.
 `Document` must be specified using its ID (see `searc` command). Please keep
 in mind that documents that are already in the word directory are never
 imported again and are simply silently ignored.

**ocr** `document`[`|page`] [`document`[`|page`] [...]] [-- [`--lang language`] [`--empty_only`]]
 Re-run the OCR on the specified elements. Elements can be whole documents or
 specific pages (see `EXAMPLE`). Specifies the `language` to use for OCR with
 `--lang` option (check OCR tool for supported `language`). The default
 `language` used is the one in Paperwork's configuration. Run through pages
 without text only using the `--empty_only` otherwise, all pages are processed.

**remove_label** `document` `label`
 Remove a `label` from a `document`. Note that if the `document` was the last
 one to use the `label`, the `label` may disappear entirely from Paperwork.
 `Document` must be specified using its ID (see `search` command).

**rename** `old` `new`
 Change the ID of a document. Note that the document id are also their date.
 Using an ID that is not a date may have side effects (the main one being the
 document won't be sorted correctly).

**rescan**
 Rescan the work directory. Look for new, updated or deleted documents and
 update the index accordingly.

**search** `keyword` [`keyword` [...]]
 List the documents containing the `keywords`. Syntax is the same than with the
 search field in Paperwork-gui. Search "" (empty string) to get all the
 documents. See **EXAMPLE**.

**show** `document`
 Show `document` information (but not its content, see `dump`). See `search`
 for the document id.

**switch_workdir** `path`
 Change current Paperwork's work directory to `path`. Does `not` update the
 index. You should run the `rescan` command after this one.

EXAMPLE
=======
* Get help for the rescan command:

  `paperwork-shell` help rescan

* Create a new label and add it to a document:

  `paperwork-shell` add_label 19700101_0000_01 important #ff0000

* Delete a document:

  `paperwork-shell` delete_doc 19700101_0000_01

* Dump the third page of a document:

  `paperwork-shell` dump 19700101_0000_01 3

* Export all documents into a folder:

  `paperwork-shell` export_all export-folder --quality 80 --format A4

* Export one document:

  `paperwork-shell` export_doc 19700101_0000_01 important_doc.pdf --quality 30

* Guess labels of a document without applying them:

  `paperwork-shell` guess_labels 19700101_0000_01

* Import a folder of PDF files into paperwork workdir:

  `paperwork-shell` import folder/

* Add an image to an existing document:

  `paperwork-shell` import image.png -- --append 19700101_0000_01

* Redo OCR on a documents with another language:

  `paperwork-shell` ocr 19700101_0000_01 -- --lang jpn

* Redo OCR on a specific page:

  `paperwork-shell` ocr "19700101_0000_01|2"

* Remove a label from a document:

  `paperwork-shell` remove_label 19700101_0000_01 important

* Rescan working:

  `paperwork-shell` rescan

* Search documents in workdir:

  `paperwork-shell` search "label:important AND paperwork"

* Show document information:

  `paperwork-shell` show 19700101_0000_01

* Change workdir

  `paperwork-shell` switch_workdir ~/papers

SEE ALSO
========
* paperwork(1)
* The paperwork frontend manual (file:///usr/share/doc/paperwork-gtk/usage.pdf)
