Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cherti/remarkable-cli-tooling

Tooling for the reMarkable paper tablet.
https://github.com/cherti/remarkable-cli-tooling

remarkable-tablet

Last synced: 26 days ago
JSON representation

Tooling for the reMarkable paper tablet.

Host: GitHub
URL: https://github.com/cherti/remarkable-cli-tooling
Owner: cherti
License: gpl-3.0
Created: 2021-09-21T21:39:53.000Z (about 3 years ago)
Default Branch: main
Last Pushed: 2024-02-19T05:45:17.000Z (10 months ago)
Last Synced: 2024-08-03T17:10:08.984Z (4 months ago)
Topics: remarkable-tablet
Language: Python
Homepage:
Size: 106 KB
Stars: 71
Watchers: 5
Forks: 6
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-reMarkable - reMarkable CLI tooling - CLI-tooling to sync documents to a reMarkable, to clean deleted files etc. without needing cloud access (Other / Launchers)

README

# remarkable CLI tooling

This repository provides a couple of tools that provide easy direct interaction with a [reMarkable paper tablet](https://remarkable.com) via the shell.
It doesn't require internet, the cloud or a remarkable account, it just works over ssh via a USB-cable connection (or local Wifi, if configured and enabled, although [additional steps may be necessary](https://www.reddit.com/r/RemarkableTablet/comments/edozpq/howto_access_the_web_interface_via_ssh/)).

*This software is not endorsed by reMarkable AS nor are any guarantees provided regarding suitability and correct functionality, use at your own risk.*

All scripts are currently tested with software versions:

* 2.9.1.217
* 2.10.3.379
* 2.11.0.442
* 2.12.1.527
* 2.12.2.573
* 2.12.3.606
* 2.14.3.1005

and should work under any unixoid operating system, such as Linux, BSD or MacOS/OSX. If you want to use these scripts under Windows, you likely need to resort to the Windows Subsystem for Linux to do so.
Where reMarkable-specific internals have changed, supported version numbers are tagged to specific commits, to make sure to mark version-specific verified software versions.
The latest version of this repository is typically tailored to the latest version of the reMarkable software.

## Summary

* `resync.py`: push documents to or pull documents from the reMarkable, or to pull everything for backup purposes
* `reclean.py`: cleanup deleted documents on the reMarkable (necessary if the cloud is not used)
* `resign.py`: temporarily transfer documents to the reMarkable to put a signature, and pull them again once it's done

## resync.py

`resync.py` provides easy direct transfer of documents and folders of documents to a reMarkable and pull documents from it again.
It includes the possibility to synchronize entire filesystem trees between devices (with the limitation of, if desired, skipping or replacing either all files or none).
By default, files will, however, simply be added to the document tree, even if they exist.

### Usage

Basic usage:
To push documents to the remarkable, use one of

resync.py push document1.pdf another_document.epub folder_with_documents ...
resync.py + document1.pdf another_document.epub folder_with_documents ...

To retrieve documents from the remarkable, use one of

resync.py pull document1.pdf some_folder/another_document folder_with_documents ...
resync.py - document1.pdf some_folder/another_document folder_with_documents ...

To pull all documents (exclude patterns still apply), use

resync.py backup

To pull documents or folders, the full path from the top level has to be provided; entire folders can also be pulled.

`resync.py` also provides a number of flags to select the destination folder, to skip already existing files or to overwrite them.
If in doubt, especially when pushing, use `--dry-run` to see what's going to happen beforehand.

Files are identified by their visible name and their parent folder, if this is not unambiguously possible, resync.py will error out.
By default all files will be copied anew to the remarkable, if you copy a file that is already there, you'll have it twice. See for example `-s` below for alternative behaviors.
Folders are never recreated, they are only created if they don't already exist.

For the full set of options, refer to `resync.py --help`:

usage: resync.py [-h] [--dry-run] [-o ] [-s | --overwrite | --overwrite_doc_only] [-e EXCLUDE_PATTERNS [EXCLUDE_PATTERNS ...]] [-r ]
[--transfer-dir ] [--debug]
mode [documents ...]

Push and pull files to and from your reMarkable

positional arguments:
mode push/+, pull/- or backup
documents Documents and folders to be pushed to the reMarkable

optional arguments:
-h, --help show this help message and exit
--dry-run Don't actually copy files, just show what would be copied (currently push only)
-o , --output
Destination for copied files, either on or off device
-v verbosity level
--if-exists {skip,new,replace,replace-pdf-only}
if the destination file already exists: *skip* pushing document (default); create a
separate *new* separate document under the same name; *replace* document; *replace-
pdf-only*: replace underlying pdf only on reMarkable, keep notes etc.
-e EXCLUDE_PATTERNS [EXCLUDE_PATTERNS ...], --exclude EXCLUDE_PATTERNS [EXCLUDE_PATTERNS ...]
exclude a pattern from transfer (must be Python-regex)
-r , --remote-address
remote address of the reMarkable
--transfer-dir
custom directory to render files to-be-upload
--debug Render documents, but don't copy to remarkable.

If you want to test this script without the risk of messing up your documents, you can make a backup of the folder `~/.local/share/remarkable/xochitl` on the remarkable to restore if anything goes wrong.

### Prequisites

* Python 3.6+
* Functioning [ssh-access](https://remarkablewiki.com/tech/ssh#passwordless_login_with_ssh_keys) to the device (practically speaking passwordless via SSH keys)
* for pull: the web-interface must be enabled (Settings > Storage > USB web interface)
* optional: Python's `termcolor`-module to add color to the dry-run output

## reclean.py (deprecated)

~`reclean.py` will clean up deleted files on your remarkable, i.e. files that are gone from trash by emptying it. Due to the reMarkable typically needing to sync this action with the reMarkable cloud, these files only actually get deleted after their deletion has been synced to the cloud. If no reMarkable account is configured, this is never, hence they indefinitely stay on the device. `reclean.py` takes that place, cleaning up those leftovers to free the space on the remarkable again.~

The above is no longer accurate, in software versions of at least 3.9.4.2018 (that's the one I could verify this for, it might have been introduced in earlier versions even) reMarkable will delete all of the data and only leave a `*.tombstone` file of negligible size (4K), which only contains a timestamp of deletion (which is probably used for reporting to the remarkable cloud on next sync).
Given that this size is negligible in size, `reclean.py` is deprecated for all use cases except the one below (which should however never happen in the first place unless something is buggy or things were manually fiddled with).

`reclean.py` can still search for orphaned documents, i.e. documents that are missing their metadata and are, as a consequence never picked up by the reMarkable UI (and they don't have a deleted flag either, as this would be noted in said metadata). Those files are cleaned up as well, if the user desires.

This includes tombstones, as they are also files without associated metadata.
That being said, ssh-ing into the device and running `rm ~/.local/share/remarkable/xochitl/*.tombstone` executes unconditionally faster than `reclean.py`.

### Usage

Basic usage:

reclean.py

For the full set of options, refer to `reclean.py --help`:

usage: reclean.py [-h] [-r ] [--dry-run]

Clean deleted files from your reMarkable

optional arguments:
-h, --help show this help message and exit
-r , --remote-address
remote address of the reMarkable
--dry-run Don't actually clean files, just show what would be done

### Prequisites
* Python 3.6+
* Functioning [ssh-access](https://remarkablewiki.com/tech/ssh#passwordless_login_with_ssh_keys) to the device (practically speaking passwordless via SSH keys)

Nothing needs to be installed on the remarkable.

## resign.py

`resign.py` will transfer documents onto the reMarkable, so you can sign them, and then pulls them again with the signature on it and deletes the document from the reMarkable again.
It requires `resync.py` to be available, so if you name `resync.py` or put it into a location that is not in `PATH`, you need to adjust the variable at the very top in `resign.py`.

### Usage

Basic usage:

resign.py document1.pdf [document2.pdf ...]

For the full set of options, refer to `resign.py --help`:

usage: resign.py [-h] [-r ] [documents ...]

Relay documents over your reMarkable for signing

positional arguments:
documents Documents and folders to be signed

optional arguments:
-h, --help show this help message and exit
-r , --remote-address
remote address of the reMarkable

### Prequisites
* Python 3.6+
* Functioning [ssh-access](https://remarkablewiki.com/tech/ssh#passwordless_login_with_ssh_keys) to the device (practically speaking passwordless via SSH keys)

Nothing needs to be installed on the remarkable.

## Limitations

At this time, this set of tools imposes two limitations on file names in your reMarkable:

* No `/` in file names, as this is the filesystem separator, messing with the proper mapping of directory trees within your remarkable onto your filesystem
* No `'` in file names, as it messes with the remote ssh command construction.

`resync` will check for these and ignore paths that contain such characters.

## Credits

These scripts are inspired by [reHackable/scripts](https://github.com/reHackable/scripts).