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 --cloud            # Read-only cloud 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)
`--cloud`	Use the reMarkable Cloud API
`--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 menu bar or system tray icon for status and control.

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

The status icon 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 or cloud — no conversion.

reMarkableSync backup
reMarkableSync backup --wifi --force-backup
reMarkableSync backup --cloud --skip-templates

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, cloud device token, AI API keys) are stored in your system keyring — never in the config file.

Cloud Setup

See Choosing a Connection Method for a detailed comparison of USB, Wi-Fi, and Cloud.

Mode	Advantages	Limitations
USB	Most reliable direct connection; includes built-in templates	Requires a cable and SSH/developer access
Wi-Fi	No cable required; includes built-in templates	Requires the same network and Wi-Fi SSH
Cloud API	Works without the tablet nearby	Slower, no system templates, and potentially incomplete without Connect

Cloud mode uses reMarkable's desktop-app API.

Run reMarkableSync config and select Cloud.
Open my.remarkable.com/device/desktop/connect.
Sign in and create a code for a new desktop app.
Enter the 8-character code in the wizard.
The wizard verifies access and stores the resulting device token in your system keyring.
Choose whether missing cloud files should be ignored or treated as deleted.
Optionally wait for folder discovery and choose which cloud folders to sync.

The temporary pairing code is never stored. Later runs reuse the device token from the keyring.

Important: without a Connect subscription, files inactive for more than 50 days may stop appearing in the cloud until reopened on the tablet. Missing cloud entries are treated as unavailable, not deleted. Cloud sync only adds or updates local files and never removes an existing backup.

The wizard defaults to Ignore missing files. If you choose Treat as deleted, only files recorded by an earlier successful cloud sync are moved into a timestamped Cloud Archive directory. The operation is reversible and never permanently deletes local data.

Built-in system templates are not exposed by the cloud API and remain available only through USB or Wi-Fi device sync.

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.