remarkable

Utilities for interacting with a reMarkable tablet and post-processing exported PDFs.

This project installs two command-line scripts:

• remarkable: terminal UI and automation commands for browsing, downloading, and uploading documents.
• remarkable-hlfix: PDF post-processing tool that reduces highlight opacity.

Installation

Install from PyPI:

pip install remarkable-tools

or with uv:

uv add remarkable-tools

To install as a standalone tool (makes remarkable and remarkable-hlfix available globally without a project):

uv tool install remarkable-tools

For development, install the package in your current environment:

uv sync

Then run scripts with uv run:

uv run remarkable --help
uv run remarkable-hlfix --help

If installed as a tool or package entry point, you can call remarkable and remarkable-hlfix directly.

Script: remarkable

remarkable connects to the tablet over the reMarkable local interface (http://10.11.99.1) and supports both interactive and one-shot modes.

Usage

Start the interactive browser:

remarkable

Start in a specific folder title path:

remarkable "Work/Meetings"

Download newest document and exit:

remarkable --get-newest

Download newest document matching a tag suffix:

remarkable --get-newest --tag _notes

Download newest document into a specific directory:

remarkable --get-newest --output-dir ./downloads

Upload a file and exit:

remarkable --upload-file ./document.pdf

Disable highlight fixing for downloaded PDFs:

remarkable --no-hl-fix

Embed page tags as bookmarks in downloaded PDFs:

remarkable --pdf-tag-bookmarks

Embed an Annotations tag bookmark for pages with reMarkable page material:

remarkable --pdf-annotation-bookmarks

Write a JSON tag report with extracted page-tag data next to downloaded files (for example My Note.pdf → My Note.tags.json):

remarkable --tag-json-report

Show installed/runtime version:

remarkable --version

Show where config files are searched (in load order):

remarkable --show-config-paths

Write logs to a custom location:

remarkable --log-file /tmp/remarkable-ui.log

Exit codes (one-shot mode)

When running one-shot actions (--get-newest or --upload-file), remarkable exits with operation-specific status codes:

Exit code	Meaning
0	Success (or no documents found for --get-newest).
2	Initialization/connect failure while creating the device session.
3	Download failure during --get-newest.
4	Upload failure during --upload-file.

On these failures, a concise error message is printed to stderr indicating whether the operation timed out, could not reach the device, or failed due to an HTTP/network error.

Interactive keys

Global:

• q: quit
• Ctrl+S: save a screenshot of the current TUI view (remarkable-ui-YYYYMMDD-HHMMSS.svg)
• F5: refresh listing
• h: toggle highlight fix for PDF downloads
• b: toggle PDF tag-bookmark embedding for PDF downloads
• a: toggle PDF annotation-bookmark embedding for PDF downloads
• H: toggle snap-to-text → /Highlight annotation conversion for PDF downloads
• t: set a tag filter used by downloads (Enter confirms, Esc cancels)
• /: filter the current view (type to narrow, Enter to apply, Esc to clear)
• ← / → or Tab / Shift+Tab: move between the folder and document panes
• Backspace: go up one folder

Selecting a folder (Enter or click) opens it. With a document selected:

• d: download as PDF (honours the HL Fix toggle)
• D: download as .rmdoc
• u: upload a file from disk (opens a file picker)

The status bar above the panes shows the current location (/ Books / Papers), the active filter as a filter: /…/ chip (only visible while filtering), the highlight-fix state, tag-bookmark state, and the active tag. Pane titles show item counts, and switch to matched/total while a filter is active.

Downloads and uploads run in the background; a toast notification reports success or failure so the UI stays responsive. you can always confirm active settings before downloading.

Script: remarkable-hlfix

remarkable-hlfix rewrites a PDF so reMarkable-style highlights are no longer fully opaque.

Default behavior:

• Targets known reMarkable highlight colors.
• Reduces fully opaque highlight fill and stroke opacity from 1.0 to 0.4.
• Preserves graphics-state scoping (q/Q) so opacity changes do not leak between sibling drawing blocks.
• Detects snap-to-text highlights (clean axis-aligned rectangles of approximately one line height) and converts them into native PDF /Highlight annotations. The original drawing is removed for the converted lines, so PDF readers render them as real text-markup highlights that can be selected and copied with the underlying text. Freehand (non-snapped) highlights fall back to the transparency pass. See docs/snap-to-annotations.md for the heuristic's design rationale and ideas for future improvement.

Usage

Basic conversion:

remarkable-hlfix input.pdf output.pdf

Run with default filenames (input.pdf -> output.pdf):

remarkable-hlfix

Apply to all fully opaque filled shapes instead of only known highlight colors:

remarkable-hlfix input.pdf output.pdf --all-colors

Tune minimum stroke width required before applying stroke transparency:

remarkable-hlfix input.pdf output.pdf --min-stroke-width 4.0

Disable snap-to-text annotation conversion (keeps all highlights as drawn rectangles and only applies the transparency pass):

remarkable-hlfix input.pdf output.pdf --no-snap-annotations

Detect highlight palette from one page and print a paste-ready color block:

remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1

Show installed/runtime version:

remarkable-hlfix --version

Show where config files are searched (in load order):

remarkable-hlfix --show-config-paths

Write logs to a custom location:

remarkable-hlfix --log-file /tmp/remarkable-hlfix.log

Configuration

Both scripts load defaults from the same config files (later files override earlier ones).

To see the exact search order on your machine, run:

remarkable --show-config-paths

or:

remarkable-hlfix --show-config-paths

This works both in project environments (uv run ...) and for globally installed tools (uv tool install ...).

Preferred config locations follow OS conventions:

• Linux/macOS: $XDG_CONFIG_DIRS/remarkable/config (default includes /etc/xdg), then $XDG_CONFIG_HOME/remarkable/config (or ~/.config/remarkable/config)
• Windows: %PROGRAMDATA%/remarkable/config, then %APPDATA%/remarkable/config

Quick start (enable tag bookmarks by default):

[general]
pdf_tag_bookmarks = true

You can still override this per run with --pdf-tag-bookmarks or --no-pdf-tag-bookmarks.

Expected format:

[general]
hl_fix = true
pdf_tag_bookmarks = false
pdf_annotation_bookmarks = false
log_file = ""
tag = ""
url = "http://10.11.99.1"

[highlight]
alpha = 0.4
alpha_threshold = 0.999
min_stroke_width = 0.1
color_tolerance = 0.1
snap_to_annotations = false
snap_line_height_min = 4.0
snap_line_height_max = 32.0
snap_min_aspect = 0.5
snap_annotation_alpha = 1.0
snap_merge_path = false

All fields are optional and fall back to the defaults shown above. Command-line arguments override config values.

Page tag report format

When --tag-json-report is enabled, each download writes a *.tags.json report alongside the downloaded file.

The report JSON includes structured sections: document, summary, pages, and raw.

This report flag is command-line only (no config option and no TUI toggle).

[general] options

Option	Default	Description
hl_fix	true	Whether to apply highlight fixing when downloading PDFs via remarkable.
pdf_tag_bookmarks	false	Whether to embed page tags from reMarkable metadata as bookmarks in downloaded PDFs.
pdf_annotation_bookmarks	false	Whether to add an Annotations tag bookmark listing pages with reMarkable material.
log_file	""	Path to the script log file used by both remarkable and remarkable-hlfix. If empty, a platform default is used.
tag	""	Tag suffix filter used by --get-newest.
url	"http://10.11.99.1"	URL of reMarkable (do not change unless reMarkable changes standard endpoint).

Default log path when log_file = "":

• remarkable:
  • Linux: $XDG_STATE_HOME/remarkable/remarkable_ui.log (fallback: ~/.local/state/remarkable/remarkable_ui.log)
  • macOS: ~/Library/Logs/remarkable/remarkable_ui.log
  • Windows: %LOCALAPPDATA%/remarkable/logs/remarkable_ui.log
• remarkable-hlfix:
  • Linux: $XDG_STATE_HOME/remarkable/remarkable_hlfix.log (fallback: ~/.local/state/remarkable/remarkable_hlfix.log)
  • macOS: ~/Library/Logs/remarkable/remarkable_hlfix.log
  • Windows: %LOCALAPPDATA%/remarkable/logs/remarkable_hlfix.log

[highlight] options

These control remarkable-hlfix behavior. Command-line flags (where available) override config values.

Option	Default	Description
alpha	0.4	Target opacity applied to highlight fill and stroke.
alpha_threshold	0.999	Minimum opacity for a shape to be considered fully opaque and eligible for reduction.
min_stroke_width	0.1	Minimum stroke width (in PDF units) required before stroke opacity is reduced. Raise this to leave thin lines untouched.
color_tolerance	0.1	Per-channel tolerance when matching fill colors against the known highlight palette.
snap_to_annotations	false	Convert snap-to-text highlight rectangles into native PDF /Highlight annotations. Disabled by default because the detector is heuristic; enable it when the source PDF reliably uses snap-to-text highlights. Detection is per-subpath, so a path containing both a snap rectangle and other shapes only converts the rectangle. Combined fill+stroke paint operators (B, b, B*, b*) are never converted, to avoid silently dropping the stroke.
snap_line_height_min	4.0	Minimum rectangle height (PDF user-space units, 1/72") that qualifies as a single text line.
snap_line_height_max	32.0	Maximum rectangle height that qualifies as a single text line.
snap_min_aspect	0.5	Minimum width/height ratio required to treat a rectangle as text-line shaped.
snap_annotation_alpha	1.0	Opacity (/CA) written into the generated /Highlight annotation.
snap_merge_path	false	When a single snap-to-text path produces several rectangles (a multi-line highlight), emit them as a single /Highlight annotation with one /QuadPoints quad per line. Disabled by default so each line remains its own annotation, matching what earlier versions produced; enable it to get one annotation per user-intent highlight.

Troubleshooting

remarkable cannot connect to device

Symptoms:

• Requests fail or time out.
• You see connection errors when listing folders or downloading files.

Checks:

1. Ensure the tablet is connected over USB and USB web interface access is enabled.
2. Verify the endpoint is reachable:

curl -I http://10.11.99.1/documents/

3. If needed, retry after reconnecting the cable and restarting the tablet's USB web interface.

config-related startup failure

Ensure the config file uses the correct TOML structure (see Configuration above).

If you are testing quickly, run with explicit flags to avoid relying on config values.

downloaded PDF highlights look unchanged

Try one of these:

1. Make sure highlight fixing is enabled (--hl-fix or toggle h in the UI).
2. Run a direct pass with remarkable-hlfix.
3. If your document uses non-standard colors, run calibration first:

remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1

4. If highlights are very thin, lower the stroke threshold:

remarkable-hlfix input.pdf output.pdf --min-stroke-width 1.0

remarkable-hlfix input errors

Common causes:

• Input path is wrong.
• File is encrypted or malformed.
• Calibration page number does not exist in the PDF.

Checks:

1. Confirm file paths are correct.
2. Start with the basic command:

remarkable-hlfix input.pdf output.pdf

3. If that fails, try opening and re-saving the PDF with another tool, then run again.