papersync

A small Go program to upload files from Google Drive into a paperless-ngx instance.

You can run papersync in manual mode or as a daemon with configurable sync intervals.

The daemon authenticates via a GCP service account and checks a google drive folder in a configurable sync interval. Every file is downloaded from Google Drive and uploaded into paperless. Upon successful consumption in paperless, the google drive file is moved to a done folder where it can be deleted periodically. If consumption fails, the document is left as-is in the source folder and retried in the next cycle. Should document consumption fail repeatly, the file can be moved or deleted manually.

Files exceeding the configured maximum file size (default 100 MB) are automatically skipped to prevent out-of-memory issues.

Prerequisites

• Go 1.25 or later
• Google Cloud project
• Paperless-ngx instance with API access
• API token for Paperless

Installation

git clone <repository-url>
cd papersync
make
sudo install -m 755 bin/papersync /usr/local/bin/papersync

Quick Start

Setup GCP Service Account

Create a Google Cloud service account that should be used for papersync authentication.

1. Go to Google Cloud Console
2. Select a project
3. Enable the Google Drive API
4. Create a service account and note its email address
5. Download the google_credentials.json JSON file

Setup Google Drive Folders

Create two folders in your Google Drive:

• Source folder: Where new documents will be uploaded (e.g., Paperless/Inbox)
• Done folder: Where processed documents will be moved (e.g., Paperless/Done)

Share both folders with the service account email and give the service account "Editor" permissions.

Get IDs for both folders:

1. Open the folder in Google Drive web interface
2. Look at the URL - the folder ID is the long string after /folders/
3. Example: https://drive.google.com/drive/folders/1a2b3c4d5e6f7g8h9i0j → Folder ID is 1a2b3c4d5e6f7g8h9i0j

Setup Paperless Token

1. Log in to your Paperless instance
2. Go to Settings → API Tokens
3. Create a new token or copy an existing one
4. Save the token to a file

Run the daemon

./papersync sync \
  --gdrive-credentials-path /path/to/credentials/google_credentials.json \
  --gdrive-source-folder-id <source-folder-id> \
  --gdrive-done-folder-id <done-folder-id> \
  --paperless-url https://your-paperless-instance.com \
  --paperless-token-path /path/to/paperless_token

Configuration

Papersync can be configured through multiple methods (in order of precedence):

1. Command line flags
2. Environment variables (prefixed with PAPERSYNC_)
3. Configuration file
4. Default values

Papersync searches for a config.yaml file in the following locations:

• ./config.yaml (current directory)
• $HOME/.papersync/config.yaml
• $HOME/.config/papersync/config.yaml
• /etc/papersync/config.yaml

Configuration Options

Required Options

• gdrive-credentials-path - Path to Google Cloud service account credentials JSON file
• gdrive-source-folder-id - Google Drive folder ID where new documents are uploaded
• gdrive-done-folder-id - Google Drive folder ID where processed documents are moved
• paperless-url - URL to your Paperless-ngx instance
• paperless-token-path - Path to file containing your Paperless API token

Optional Options

• gdrive-allowed-extensions - List of allowed file extensions (default: .pdf, .doc, .xls, .ppt, .docx, .xlsx, .pptx)
• paperless-tags - List of tag IDs to apply to uploaded documents (default: empty)
• sync-interval-minutes - How often to check for new files in minutes (default: 60)
• sync-dry-run - Run in dry-run mode without actually uploading or moving files (default: false)
• sync-max-file-size-mb - Maximum file size in MB to process (default: 100). Files larger than this will be skipped to prevent out-of-memory issues
• log-level - Logging level: DEBUG, INFO, WARN, ERROR (default: INFO)
• prometheus-listen-addr - Prometheus metrics server listen address (default: :9123)

Usage

Show version information

./papersync version

Display current configuration

./papersync config

Run the sync daemon (continuously sync files)

./papersync sync

List pending files in Google Drive source folder

./papersync gdrive list --pending

List done files in Google Drive done folder

./papersync gdrive list --done

Download a specific file from Google Drive

./papersync gdrive fetch <file-id>

Move a file to the done folder

./papersync gdrive finish <file-id>

Upload a file to Paperless and wait for completion

./papersync paperless upload <file-path>