paperless-ngx-cli (pypaperless-cli2)

Paperless-ngx Command-Line Interface

This is a fork of Marcel Brückner's pypaperless-cli.

After updating my Paperless-ngx instances to version 3.x the current pypaperless-cli package has thrown some errors when editing documents. I republished the current pypaperless-cli as pypaperless-cli2 with the pypaperless dependency updated to ^5.1.0 for compatibility with Paperless-ngx ≥3.0 (which rejects the older API versions requested by pypaperless 4.x with 406 Not Acceptable). The pngx command and all usage below are unchanged from upstream.

Usage

# Run pngx -h for help
$ pngx [ command ] [ subcommand ] [ arguments and parameters ]

Log in to your Paperless-ngx instance which will be used in subsequent commands.

# Log in to the given host and save account credentials as default
$ pngx auth login https://paperless.example.com --ask-token
# Delete saved credentials from disk
$ pngx auth logout

Show details of a document with specific ID

# Run pngx document show -h for help
$ pngx document show <ID>
Title                      2024-01-10_RE12345678                                                                      
ID                         400                                                                                        
ASN                        None                                                                                       
Created                    2024-01-10
Correspondent              Stadtwerke
Document type              Rechnung
Storage path               None
Tags                       Rechnung
Owner                      j.pirner
Details                    https://paperless.example.com/documents/400/details/
Permissions
View
  Users                    alice, bob
  Groups                   Buchhaltung
Change
  Users                    alice
  Groups                   None
Custom fields
  Rechnungsnummer          RE12345678

Update a document's title and correspondent.

# Set document title to "My new document title" and set specific correspondent
$ pngx document edit <ID> --title "My new document title" --correspondent <CORRESPONDENT_ID>

Update a document's creation date.

The Paperless-ngx API expects the date in ISO 8601 format. With Version 0.2.0 of this package comes a dateparser which auto-detects the used date format and converts it to ISO 8601 format.

# Set document creation date to "14.09.2026"
$ pngx document edit <ID> --created-date 14.09.2026
# The date parser automatically converts the date to 2026-09-14 and uses it in the communication with the API

Assign or unassign a document's tags.

Tags can be specified by ID or the exact name. If your tag name contains spaces, wrap it in quotes.

You can add and remove multiple tags at once, separated by space.

# Add or remove one or multiple tags to/from a document given the ID or _exact_ name
$ pngx document edit <ID> --add-tags <ID|EXACT_NAME> [ID|EXACT_NAME]
$ pngx document edit <ID> --remove-tags <ID|EXACT_NAME> [ID|EXACT_NAME]

Add, update or remove custom fields.

Similar to tags, custom fields can be specified by ID or the exact name, which must be quoted if it contains spaces. In addition, custom fields can have a value that can be passed in a KEY=VALUE style. Make sure your value adheres to the custom field's type. If your custom field name contains an equal sign, refer to it by its ID.

You can add and remove multiple custom fields at once, separated by space.

# Add/Update or remove custom field given the ID or _exact_ name
$ pngx document edit <ID> --add-custom-fields <ID|EXACT_NAME>[=VALUE] [<ID|EXACT_NAME>[=VALUE]]
$ pngx document edit <ID> --remove-custom-fields <ID|EXACT_NAME> [<ID|EXACT_NAME>]

Set or remove a document's owner.

Similar to tags, the owner can be specified by ID or the exact (case-insensitive) username.

# Set the owner given the ID or _exact_ username
$ pngx document edit <ID> --owner <ID|EXACT_USERNAME>
# Remove the owner, leaving the document unowned
$ pngx document edit <ID> --remove-owner

# Make "j.pirner" the owner of document 1489
$ pngx document edit 1489 --owner j.pirner
# Same, but referring to the user by ID
$ pngx document edit 1489 --owner 3

--owner and --remove-owner are mutually exclusive.

Grant or revoke view and change permissions.

Permissions are granted to users and groups separately. Users can be specified by ID or the exact (case-insensitive) username, groups by ID or the exact group name. If your username or group name contains spaces, wrap it in quotes.

You can add and remove multiple users or groups at once, separated by space, and IDs and names can be mixed freely.

# Grant or revoke view permission given the ID or _exact_ name
$ pngx document edit <ID> --add-view-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
$ pngx document edit <ID> --remove-view-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
$ pngx document edit <ID> --add-view-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
$ pngx document edit <ID> --remove-view-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]

# Grant or revoke change permission given the ID or _exact_ name
$ pngx document edit <ID> --add-change-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
$ pngx document edit <ID> --remove-change-users <ID|EXACT_USERNAME> [<ID|EXACT_USERNAME>]
$ pngx document edit <ID> --add-change-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]
$ pngx document edit <ID> --remove-change-groups <ID|EXACT_NAME> [<ID|EXACT_NAME>]

# Let "alice" and user 42 view document 1489
$ pngx document edit 1489 --add-view-users alice 42
# Let the group "Buchhaltung" view and change it
$ pngx document edit 1489 --add-view-groups Buchhaltung --add-change-groups Buchhaltung
# Revoke "bob"'s change permission
$ pngx document edit 1489 --remove-change-users bob
# Group name containing spaces
$ pngx document edit 1489 --add-view-groups "Externe Buchhaltung"

Permission changes are applied incrementally: existing entries you don't mention are kept. All permission parameters can be combined in a single call, together with any other parameter.

# Hand the document over to the accounting department in one go
$ pngx document edit 1489 --title "Stadtwerke Jahresabrechnung 2024" --owner j.pirner \
    --add-view-groups Buchhaltung --add-view-users alice 42 \
    --add-change-users alice --remove-change-users bob

pngx document show displays the owner and the full permission table (see above). Resolving users and groups to names requires an account that may read /api/users/ and /api/groups/. If it may not, IDs are shown instead and --owner/--add-*/--remove-* only accept numeric IDs.

Configuration

The Paperless-ngx CLI client can be configured in a variety of ways. In order of precedence from lowest (most easily overridden) to highest (overrides all others), it offers the following configuration sources:

• applications defaults
• configuration file
• environment variables
• command-line parameters

Application defaults

There's only one application default:

• the CLI client configuration file (which defaults to $XDG_CONFIG_HOME/pngx/pngx.toml¹)

Configuration file

The Paperless-ngx CLI client can read all basic configuration (the Paperless-ngx server's authentication information) from its configuration file (pngx.toml). A custom file path can be specified via:

• command-line parameter (--config)
• environment variable ($PNGX_CONFIG)

If both are specified, the command-line parameter takes precedence. Otherwise, it uses the first pngx.toml file found at these locations in order:

• $PWD/pngx.toml
• $XDG_CONFIG_HOME/pngx/pngx.toml (application default)

If no configuration file can be found, it will be created at the application default location.

Run pngx --show-config to get the configuration file path in use.

# Default configuration path if no pngx.toml exists in current working directory
$ pngx --show-config
/Users/marcelbrueckner/.config/pngx/pngx.toml

Obviously, you can't specify a configuration path within the configuration file itself.

Environment variables

If you don't want your credentials to be stored on disk, you can use environment variables or ad-hoc session parameters (see command-line below)

Environment variables have a higher precedence than entries in pngx.toml. Existing environment variables override corresponding values in your configuration file. If you can't connect to your Paperless-ngx instance, make sure you don't have accidentially mixed values from your configuration file and environment.

• PNGX_HOST

• PNGX_USER

• PNGX_TOKEN

• PNGX_CONFIG

Command-line parameters

You can use the command-line to log in to your Paperless-ngx instance. The credentials provided will be saved to your configuration file.

# Store your credentials for subsequent usage
# Your credentials might end up in your shell history, so be cautious! 

# Don't do that
$ pngx auth login --host=https://paperless.example.com --user=username --password=password
# Use this instead
$ pngx auth login --host=https://paperless.example.com --user=username --ask-password|--ask-token

If you don't want your credentials saved to file, use them as ad-hoc session parameters.

$ pngx --host=https://paperless.example.com --user=username --ask-password|--ask-token auth show

Caveats

Paperless-ngx CLI allows you to add servers whose API can be accessed without authentication. However, the underlying pypaperless library this CLI is using doesn't look like it supports anything else than token authentication. I guess that you will likely run into errors if you don't use token authentication on your Paperless-ngx server instance. Maybe a token can be generated while using remote user auth, but it's untested at this point.

This fork has been checked against Paperless-ngx 3.0.5; the upstream project was tested against v2.5.3. As with upstream, compatibility depends on the pypaperless library tracking whatever HTTP API version Paperless-ngx currently requires.

1. In case you don't know about the XDG Base Directory Specification, check out their docs. ↩