remarkable-tools 0.2.1

A set of tools to interact with reMarkable tablets

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

Configuration files

Defaults are loaded from these files (later files override earlier ones):

Linux/Unix:

1. /usr/local/etc/remarkableconfig
2. $XDG_CONFIG_HOME/remarkable/config
3. ~/.config/remarkable/config
4. ~/.remarkableconfig

Windows:

1. %PROGRAMDATA%/remarkable/config
2. %APPDATA%/remarkable/config
3. %LOCALAPPDATA%/remarkable/config
4. %USERPROFILE%/.remarkableconfig

Expected format:

[general]
hl_fix = true
tag = ""
start_folder = ""

Command-line arguments override config values.

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

Upload a file and exit:

remarkable --upload-file ./document.pdf

Disable highlight fixing for downloaded PDFs:

remarkable --no-hl-fix

Show installed/runtime version:

remarkable --version

Interactive keys

• q: quit
• F5: refresh
• h: toggle highlight fix for PDF downloads
• In folder list: Enter to open folder
• In document list: d to download PDF, D to download .rmdoc

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.

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

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

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

If you use a config file, ensure it contains a [general] table:

[general]
hl_fix = true
tag = ""
start_folder = ""

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.