reMarkableSync

A comprehensive Python toolkit for backing up reMarkable tablet notebooks, converting them to PDF, and transcribing handwriting to Markdown with AI — over USB or Wi-Fi.

[!IMPORTANT] Known device support:

• reMarkable 2 — confirmed working and the primary device tested
• reMarkable Paper Pro — expected to work, but SSH must be enabled through developer mode, which currently requires a factory reset
• reMarkable 1 — not currently verified; compatibility is not guaranteed

AI handwriting-to-text features work with GitHub Copilot, Claude (Anthropic), or Google Gemini (free tier available).

Device Compatibility

Features

• USB, Wi-Fi & cloud sync — use the tablet directly or sync without it through the cloud
• Incremental backup — only downloads files that have changed (tracked by size, mtime, and MD5)
• PDF conversion — v5 and v6 .rm formats with template backgrounds, folder hierarchy preserved
• AI handwriting recognition — send page images to GitHub Models (GPT-4o), Claude, or Google Gemini
• Markdown export — each notebook becomes a .md file with YAML frontmatter and embedded page images
• Watch mode — automatic periodic sync with system-tray status icon and run-at-startup option
• Secure credential storage — SSH password and AI tokens stored in your system keyring

Supported AI Providers

Quick Start

1. Install

# macOS (Homebrew)
brew tap jeffsteinbok/remarkablesync && brew install remarkablesync

# All platforms (pip)
pip install remarkablesync

# Or download a pre-built executable from the Releases page

2. Run the configuration wizard

reMarkableSync config

The wizard walks you through:

[!TIP] Multi-device setup: Use the folder filter to sync different tablet folders to different computers — e.g., sync your "Work" folder to your work PC and "Home" to your personal machine. Each machine gets its own config.

3. Run it

reMarkableSync watch

This will use your configured defaults and launch a sync cycle (backup → PDF → Markdown), then keep running and re-sync every 30 minutes. Check your output directories to verify everything looks right.

4. Set it to run at startup

Once you're happy with the output, enable run-at-startup from the menu bar or system tray icon (or via the watch command). reMarkableSync will sync your tablet automatically in the background whenever your computer is on.

[!TIP] Obsidian users: Point the Markdown output directory at a folder inside your Obsidian vault. Your handwritten notes appear as searchable Markdown with embedded page images. Pair with Obsidian OneDrive Sync to sync your vault across devices.

AI Provider Setup

The AI handwriting-to-text features require either a GitHub Copilot account (for GitHub Models) or a Claude (Anthropic) API key. Support for additional providers can be added as needed.

Both AI provider SDKs are installed with pip install -r requirements.txt. The config wizard handles authentication interactively.

GitHub Models

The wizard runs a GitHub device-code flow to authenticate. No manual token setup needed.

Alternatively, set a GITHUB_TOKEN environment variable with a PAT that has models:read scope.

Claude (Anthropic)

1. Go to https://console.anthropic.com/settings/keys
2. Click Create Key and copy it (starts with sk-ant-api03-...)
3. Paste it into the config wizard — it's saved in your system keyring

Default model: claude-sonnet-4-6.

Usage

After running config, most users only need watch. For one-off or scripted use:

# Default: backup + PDF conversion (uses saved config)
reMarkableSync

# Full pipeline: backup + PDF + AI OCR + Markdown
reMarkableSync md --with-backup --with-pdf

# Individual steps
reMarkableSync backup          # backup only
reMarkableSync convert         # PDF conversion only (from existing backup)
reMarkableSync md              # Markdown export only (from existing PDFs)

# Watch mode (periodic sync)
reMarkableSync watch           # uses saved config for interval, dirs, AI

# Check for updates
reMarkableSync check-update

Command Line Options

All commands read defaults from the saved config. CLI flags override config values.

Common:

• -d, --backup-dir PATH — backup directory
• -v, --verbose — debug logging
• --version — version info

Connection:

• --host HOST — tablet IP (default: 10.11.99.1)
• --wifi — connect over Wi-Fi
• --wifi-host HOST — tablet Wi-Fi IP (auto-discovered if omitted)
• --cloud — use the reMarkable Cloud API

Backup:

• -p, --password — SSH password (prompted if not saved)
• --skip-templates — don't backup templates
• --force-backup — re-download everything

Convert:

• -o, --output-dir PATH — PDF output directory
• --force-all — reconvert all notebooks
• --sample N — convert first N notebooks only
• --notebook NAME — convert a single notebook

Markdown (md):

• -V, --vault-dir PATH — Markdown output directory
• --ai-provider — github or claude
• --ai-model — override default model
• --ai-api-key — API key (prefer keyring or env vars)
• --tags — comma-separated frontmatter tags (default: remarkable)
• --no-images — skip embedding page images
• --with-backup / --with-pdf — include earlier pipeline stages
• --force-export — re-export all notes

Watch:

• -i, --interval N — minutes between syncs (default: 30)
• --systray / --no-systray — menu bar or system tray icon (default: enabled)

Updates:

• reMarkableSync check-update — check for newer versions
• Update notifications appear automatically (checked once per day)

Wi-Fi Connection

The config wizard can enable Wi-Fi SSH on your tablet automatically via USB. If you prefer to do it manually:

1. Connect tablet via USB and SSH into 10.11.99.1
2. Run rm-ssh-over-wlan on
3. Find the IP: ip addr show wlan0
4. Use that IP in the config wizard or --wifi-host

[!TIP] Assign a static DHCP lease to your tablet in your router so the IP doesn't change.

Cloud Connection

Cloud mode downloads the same raw notebook structure used by device backups and stores its device token in the system keyring. It is read-only and never uploads, renames, moves, or deletes cloud content.

To configure it:

1. Run reMarkableSync config and select Cloud.
2. Open https://my.remarkable.com/device/desktop/connect.
3. Sign in and create a code for a new desktop app.
4. Enter the 8-character code in the wizard.
5. The wizard verifies access and stores the resulting device token in the system keyring.
6. Choose how missing cloud files should be handled:
   • Ignore missing files and keep the local backup (default).
   • Treat them as deleted by moving previously cloud-synced files into a timestamped Cloud Archive directory. Nothing is permanently deleted.
7. Optionally wait for the cloud folder list and select which folders to sync.

The pairing code is temporary and is not stored. Future runs reuse the keyring token.

Without a Connect subscription, files inactive for more than 50 days may stop appearing in the cloud until opened again on the tablet. A missing cloud item is therefore treated as unavailable, not deleted: cloud sync only adds or updates files and never removes an existing local backup. Built-in system templates are only available through device sync.

The wizard explains the tradeoffs before asking:

Generated Markdown Format

Each notebook becomes a folder with one Markdown file per page:

---
title: "My Meeting Notes"
source: reMarkable
remarkable_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
notebook: Work
folder: Work/Meetings
page: 1
created: 2025-01-15
ai_provider: GitHubModelsProvider
ai_model: gpt-4o-mini
tags:
  - remarkable
---

## Action Items

- **Follow up** with Alice on the Q1 plan
- Schedule review for next Friday

![page 1](_images/page_001.png)

Page images are stored in a _images/ subfolder next to the Markdown files.

Troubleshooting

For any issue, re-run your command with --log-level DBG to get detailed output. See How to get DEBUG logs for details.

Acknowledgements

reMarkableSync is built on top of these excellent open-source projects:

Security

• SSH passwords, cloud device tokens, and AI tokens are stored in your system keyring
• USB and Wi-Fi stay on the local network; cloud mode connects to reMarkable's servers
• Config file at <AppData>/remarkablesync/config.json contains only non-secret settings