Papermerge Cli

Command line utility which uses REST API to interact with your Papermerge DMS instance. It can be used to:

  • upload/import documents from local filesystem

  • download documents and folder

  • search through documents


Upload documents with papermerge-cli command line utility


In order to use papermerge-cli you need to have python installed. You need python version >= 3.10.


Install papermerge-cli with following command:

$ pip install papermerge-cli

pip is package installer for python - it usually comes with python interpreter. In order to install pip on Ubuntu use following command:

$ sudo apt install python3-pip


Papermerge Cli is configured via environment variables:



as the name suggests, the first one is the host of the REST API server and second value is the REST API token.

REST API server should be specified with http:// or https:// prefix, but without the /api suffix. Valid values examples: http://papermege.local,


The host may or may not contain the /. E.g. http://papermege.local and http://papermerge.local/ are both valid values and point to the same host

REST API token can be obtained either from Papermerge DMS user menu -> API Tokens or directly from command line by using auth subcommand:

$ papermerge-cli auth

Papermerge Cli will prompt you for username and password. On successfull authentication your REST API token will be displayed - now you can use this token for all subsequent authentications.


REST API host can be provided by command line option --host


In order to get general help about the command use:

$ papermerge-cli --help

In order to get help for individual commands, place --help flag after the command:

$ papermerge-cli import --help

List - Browse Nodes

Now, with PAPERMERGE_CLI__HOST and PAPERMERGE_CLI__TOKEN environment variables set you can use list content of you home folder:

$ papermerge-cli list

In order to list content of specific folder (including inbox folder):

$ papermerge-cli list --parent-uuid=UUID-of-the-folder

Me - Current User Details

In order to see current user details (current user UUID, home folder UUID, inbox folder UUID, username etc):

$ papermerge-cli me

List Preferences

List all preferences:

$ papermerge-cli pref-list

List specific section of the preferences:

$ papermerge-cli pref-list --section=ocr

Show value of preference trigger from section ocr:

$ papermerge-cli pref-list --section=ocr --name=trigger

Update Preferences

Update value of the preference trigger from section ocr:

$ papermerge-cli pref-update --section=ocr --name=trigger --value=auto

Import Folders/Documents

Recursively imports folder from local filesystem. For example, in order to import recursively all documents from local folder:

$ papermerge-cli import /path/to/local/folder/

You can also import one single document:

$ papermerge-cli import /path/to/some/document.pdf

If you want the local copy the uploaded documents to be deleted after successful import - use --delete flag:

$ papermerge-cli import --delete /path/to/folder/


Be extremely careful with --delete flag! When present, papermerge-cli will irreversible delete the local copy of all documents and folders in the /path/to/folder/!


--delete flag deletes the local copy of the documents/path to import after successful upload - this means that even if though you local copy of the documents vanished - the originals are still available in Papermerge DMS!


Downloads a folder or a document:

$ papermerge-cli download --uuid <document or folder uuid>

In case uuid is the ID of specific folder - a zip file will be downloaded; zip file will contain all nodes insides specified folder.

You can use –uuid multiple times:

$ papermerge-cli download --uuid <uuid of doc1> --uuid <uuid of doc2> --uuid <uuid of folder 1>

If you want to download content to specific file on your file-system, use -f option:

$ papermerge-cli download --uuid <doc-uuid> -f /path/to/file-system/document.pdf

or in case of uuid is a folder:

$ papermerge-cli download --uuid <folder-uuid>  -f /path/to/file-system/

You can also specify the format/type of the downloaded archive (e.g. in case node is either a folder):

$ papermerge-cli download --uuid <folder-uuid>  -f /path/to/file-system/folder.targz -t targz