Advanced Usage

Command reference and configuration options for power users.

Commands

reMarkableSync sync

The default workflow — backs up your tablet and converts any updated notebooks to PDF.

reMarkableSync sync                    # USB connection
reMarkableSync sync --wifi             # Wi-Fi connection
reMarkableSync sync --force-backup     # Re-download all files
reMarkableSync sync --force-convert    # Re-convert all notebooks

Option	Description
`--wifi`	Use Wi-Fi instead of USB
`--wifi-host HOST`	Specify Wi-Fi IP/hostname (default: auto-discover)
`--force-backup`	Force full backup, ignoring incremental state
`--force-convert`	Re-convert all notebooks to PDF
`--skip-templates`	Skip backing up template files
`--log-level LEVEL`	Set verbosity: `DBG`, `INF`, `WRN`, `ERR`

reMarkableSync watch

Runs sync automatically on a schedule with a system tray icon for status and control.

reMarkableSync watch                   # Default interval from config
reMarkableSync watch --interval 300    # Sync every 5 minutes

The system tray menu lets you:

Sync Now — trigger an immediate sync
Pause / Resume syncing
Change the sync interval
Open backup, PDF, or Markdown folders
View the log file
Enable "Run at Startup"

reMarkableSync backup

Only download files from the tablet — no conversion.

reMarkableSync backup
reMarkableSync backup --wifi --force-backup

reMarkableSync convert

Only convert already-backed-up notebooks to PDF — no tablet connection needed.

reMarkableSync convert
reMarkableSync convert --force-convert

Full Pipeline

The pipeline command runs the complete flow: backup → PDF → AI OCR → Markdown export.

reMarkableSync pipeline \
  --output-dir ~/Documents/Notes \
  --ai-provider github

Option	Description
`--output-dir DIR`	Root directory for Markdown output
`--ai-provider`	`github` (GitHub Copilot) or `claude`
`--ai-model MODEL`	Override the default AI model
`--skip-backup`	Skip the backup stage
`--skip-convert`	Skip PDF conversion
`--force-export`	Re-export all notes even if unchanged
`--notebook-filter PATTERN`	Only process matching notebooks
`--no-ai-ocr`	Export without AI transcription
`--tags TAGS`	Comma-separated tags for frontmatter

Logging & Debugging

All commands accept --log-level DBG for detailed output. A log file is also written to your backup directory's parent folder at remarkablesync.log.

reMarkableSync sync --log-level DBG

See How to get DEBUG logs for full details on log file locations.

Configuration

Settings are stored in <AppData>/remarkablesync/config.json. You can edit this file directly or re-run reMarkableSync config at any time.

Sensitive values (SSH password, AI API keys) are stored in your system keyring — never in the config file.

Custom OCR Instructions

You can customize how the AI transcribes your handwriting by providing a Markdown file with additional instructions. This is useful for:

Specifying terminology, abbreviations, or jargon specific to your field
Instructing the AI to format output in a particular way
Adding context about your handwriting style

Setup

Create a file at the default location:

# macOS/Linux
~/.config/remarkablesync/custom_instructions.md

# Windows
%APPDATA%\remarkablesync\custom_instructions.md

Or specify a custom path during reMarkableSync config when prompted for "Custom OCR instructions file".

Example

# Custom OCR Instructions

- I use "K8s" as shorthand for Kubernetes
- Convert "→" arrows to "->" in code contexts
- My handwritten "l" and "1" look similar - prefer letters in words
- Format any code snippets with proper markdown fencing

Pre/Post Sync Commands

You can run custom shell commands before and after each sync cycle. This is useful for:

Git commits after sync completes
Sending notifications
Triggering external backup tools
Running custom scripts

Setup

Add these fields to your config.json:

{
  "pre_sync_command": "echo 'Starting sync...'",
  "post_sync_command": "cd ~/Notes && git add -A && git commit -m 'Auto-sync'"
}

Field	When it runs
`pre_sync_command`	Before backup starts
`post_sync_command`	After all sync actions complete (backup, PDF, OCR)

Commands run in a shell (sh -c on macOS/Linux, cmd /c on Windows). If a pre-sync command fails, the sync continues. Post-sync command failures are logged but don't affect the sync result.