Metadata-Version: 2.4
Name: remarkable-tools
Version: 0.2.1
Summary: A set of tools to interact with reMarkable tablets
Keywords: remarkable,pdf
Author: Gustaf Hendeby
Author-email: Gustaf Hendeby <hendeby@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Requires-Dist: pikepdf>=10.5.1
Requires-Dist: requests>=2.32.5
Requires-Dist: textual>=8.0.0
Requires-Dist: textual-fspicker>=1.0.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

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

```bash
uv sync
```

Then run scripts with `uv run`:

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

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

Command-line arguments override config values.

### Usage

Start the interactive browser:

```bash
remarkable
```

Start in a specific folder title path:

```bash
remarkable "Work/Meetings"
```

Download newest document and exit:

```bash
remarkable --get-newest
```

Download newest document matching a tag suffix:

```bash
remarkable --get-newest --tag _notes
```

Upload a file and exit:

```bash
remarkable --upload-file ./document.pdf
```

Disable highlight fixing for downloaded PDFs:

```bash
remarkable --no-hl-fix
```

Show installed/runtime version:

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

```bash
remarkable-hlfix input.pdf output.pdf
```

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

```bash
remarkable-hlfix
```

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

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

Tune minimum stroke width required before applying stroke transparency:

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

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

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

Show installed/runtime version:

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

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

```toml
[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:

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

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

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

```bash
remarkable-hlfix input.pdf output.pdf
```

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