Metadata-Version: 2.4
Name: remarkablesync
Version: 2.0.0
Summary: Backup and convert reMarkable tablet notebooks to PDF
Home-page: https://github.com/JeffSteinbok/RemarkableSync
Author: Jeff Steinbok
Author-email: 
License: MIT
Keywords: remarkable tablet backup pdf converter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko>=3.0.0
Requires-Dist: scp>=0.14.5
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pathlib2>=2.3.7
Requires-Dist: cryptography>=41.0.0
Requires-Dist: PyPDF2>=3.0.0
Requires-Dist: svglib>=1.5.0
Requires-Dist: reportlab>=4.0.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: InquirerPy>=0.3.4
Requires-Dist: PyMuPDF>=1.23.0
Requires-Dist: rmc>=0.3.0
Requires-Dist: pdf2image>=1.16.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: pystray>=0.19.5
Requires-Dist: anthropic>=0.30.0
Requires-Dist: openai>=1.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# RemarkableSync

![RemarkableSync](githubSocial.png)

[![GitHub](https://img.shields.io/badge/GitHub-RemarkableSync-blue?logo=github)](https://github.com/JeffSteinbok/RemarkableSync)
[![GitHub release](https://img.shields.io/github/v/release/JeffSteinbok/RemarkableSync)](https://github.com/JeffSteinbok/RemarkableSync/releases)
[![CI](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/ci.yml/badge.svg)](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/ci.yml)
[![Build Executables](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/build-executables.yml/badge.svg)](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/build-executables.yml)
[![PyPI version](https://img.shields.io/pypi/v/remarkablesync.svg)](https://pypi.org/project/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]
> Tested on reMarkable 2. Compatibility with reMarkable 1 is not guaranteed.
>
> AI handwriting-to-text features require a **GitHub Copilot** or **Claude** (Anthropic) account. Support for additional providers can be added as needed.

## Features

- **USB & Wi-Fi sync** — connect via cable or wirelessly over your local network
- **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) or Claude for transcription
- **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

## Quick Start

### 1. Install

```bash
# 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

```bash
RemarkableSync config
```

The wizard walks you through:

| Setting | Default |
|---------|---------|
| **Connection mode** | USB or Wi-Fi (wizard can enable Wi-Fi SSH for you) |
| **SSH password** | Saved to system keyring |
| **Backup directory** | `<AppData>/remarkablesync/backup` (internal sync data) |
| **PDF output** | `~/Documents/RemarkableSync/PDF` |
| **Markdown output** | `~/Documents/RemarkableSync/Markdown` |
| **AI provider** | GitHub Models (free) or Claude (requires API key) |
| **AI token** | Stored securely in system keyring |
| **Folders** | Choose which tablet folders to sync (or all) |

> [!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.

> [!TIP]
> Clear any directory field and press Enter to reset it to the default.

### 3. Run it

```bash
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 system tray icon menu (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](https://github.com/JeffSteinbok/obsidian-onedrive) 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:

```bash
# 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
```

### 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)

**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` — system tray icon (default: enabled)

## 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.

## Generated Markdown Format

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

```markdown
---
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

| Problem | Fix |
|---------|-----|
| Can't connect via USB | Verify cable, ping `10.11.99.1`, check SSH password |
| Can't connect via Wi-Fi | Same network? Try `ping remarkable.local` or use `--wifi-host <ip>` |
| AI OCR returns errors | Check API key/token, verify package installed (`anthropic` or `openai`), check rate limits |
| Empty Markdown files | AI provider may have failed — check log file for details |
| Watch lock error | Delete `<backup-dir>/.remarkable_watch.lock` |
| Permission errors | Ensure output directories are writable; run as admin on Windows if needed |

## Security

- SSH password and AI tokens are stored in your **system keyring** (never in plain-text config files)
- All communication is over your local network (USB or LAN) — nothing goes to the internet except AI API calls
- Config file at `<AppData>/remarkablesync/config.json` contains only non-secret settings
