{"id":48917189,"url":"https://github.com/andrader/rm2-templater","last_synced_at":"2026-04-17T03:09:58.996Z","repository":{"id":346047394,"uuid":"1044634808","full_name":"andrader/rm2-templater","owner":"andrader","description":"A command-line tool for managing custom templates on your reMarkable 2 tablet. Easily add, remove, and organize templates with automatic image conversion and SSH-based deployment.","archived":false,"fork":false,"pushed_at":"2026-03-22T00:40:11.000Z","size":36,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T14:55:56.416Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrader.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T01:46:34.000Z","updated_at":"2026-03-22T00:40:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/andrader/rm2-templater","commit_stats":null,"previous_names":["andrader/rm2-templater"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/andrader/rm2-templater","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Frm2-templater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Frm2-templater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Frm2-templater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Frm2-templater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrader","download_url":"https://codeload.github.com/andrader/rm2-templater/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrader%2Frm2-templater/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31913118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-17T03:09:58.507Z","updated_at":"2026-04-17T03:09:58.989Z","avatar_url":"https://github.com/andrader.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reMarkable 2 Template Manager\n\nA command-line tool for managing custom templates on your reMarkable 2 tablet. Easily add, remove, and organize templates with automatic image conversion and SSH-based deployment.\n\n## Features\n\n- **SSH Key Setup**: Automatically generate and install SSH keys for passwordless access\n- **Template Management**: Add, list, remove, and backup templates\n- **Image Conversion**: Automatically converts images to reMarkable's required format (1872x1404, 226 DPI grayscale PNG)\n- **Category Organization**: Organize templates into custom categories\n- **Safe Operations**: Automatic backups before any changes\n- **Batch Processing**: Add multiple templates from directories\n\n## Installation\n\n### Recommended: Install with uv\n\n#### Install globally (best for repeated use):\n```bash\nuv tool install git+https://github.com/andrader/rm2-templater.git\n```\n- Installs the CLI globally for easy reuse: just run `rm2` or `rm2-templater`.\n\n#### Run instantly (no install, best for one-off use):\n```bash\nuvx --from git+https://github.com/andrader/rm2-templater.git --help\n```\n- Runs the CLI directly from the repo, no global install or environment changes.\n\nTo uninstall:\n```bash\nuv tool uninstall rm2-templater\n```\n\nChoose `uv tool install` for persistent, system-wide access. Use `uvx` for quick, disposable runs without installing anything globally.\n\n---\n\n### Alternative: Install with pip\n\n```bash\npip install rm2-templater\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/andrader/rm2-templater.git\ncd rm2-templater\npip install -e .\n```\n\n## Quick Start\n\n### 1. Find Your reMarkable's Connection Info\n\nOn your reMarkable 2:\n\n1. Go to **Settings** (bottom left)\n2. Select **Help** (bottom of menu)\n3. Tap **Copyrights and licenses**\n4. Scroll to **GPLv3 Compliance** section\n5. Note the IP address, username (usually `root`), and password\n\n### 2. Set Up SSH Access\n\n```bash\nrm2 setup-ssh\n# Enter your reMarkable's root password when prompted\n```\n\nThis command:\n\n- Generates an SSH key pair if one doesn't exist\n- Installs your public key on the reMarkable\n- Enables passwordless access for future operations\n\n### 3. Add Your First Template\n\n```bash\n# Add a single template\nrm2 add my-template.png\n\n# Add multiple templates with a custom category\nrm2 add template1.jpg template2.png --category \"Work\"\n\n# Add all images from a directory\nrm2 add ./my-templates/\n```\n\n## Commands\n\n### `setup-ssh`\n\nInstall your SSH public key on the reMarkable for passwordless access.\n\n```bash\nrm2 setup-ssh\n```\n\n### `add`\n\nConvert and upload template images to your reMarkable.\n\n```bash\nrm2 add [OPTIONS] PATHS...\n\nOptions:\n  -c, --category TEXT    Additional category besides 'Custom'\n  --force               Overwrite existing template entries\n```\n\n**Examples:**\n\n```bash\n# Basic usage\nrm2 add notebook-template.png\n\n# Add with custom category\nrm2 add planner.jpg --category \"Productivity\"\n\n# Add multiple files\nrm2 add template1.png template2.jpg template3.webp\n\n# Add all images from a directory\nrm2 add ./templates-folder/\n\n# Force overwrite existing template\nrm2 add existing-template.png --force\n```\n\n### `list`\n\nDisplay all current templates and their categories.\n\n```bash\nrm2 list\n```\n\n### `remove`\n\nRemove templates by name, filename, or category.\n\n```bash\nrm2 remove [OPTIONS]\n\nOptions:\n  --name TEXT           Remove by display name\n  --filename TEXT       Remove by filename (e.g. Custom/my_template)\n  --category TEXT       Remove ALL entries in a category\n  --delete-files        Also delete remote PNG files\n  -y                    Skip confirmation prompt\n```\n\n**Examples:**\n\n```bash\n# Remove by name\nrm2 remove --name \"My Template\"\n\n# Remove by filename\nrm2 remove --filename \"Custom/my_template\"\n\n# Remove all templates in a category\nrm2 remove --category \"Work\"\n\n# Remove and delete files without confirmation\nrm2 remove --name \"Old Template\" --delete-files -y\n```\n\n### `backup`\n\nCreate a timestamped backup of your templates.json file.\n\n```bash\nrm2 backup\n```\n\n## Configuration\n\nThe tool uses these default settings, which can be customized via environment variables:\n\n```python\nREMARKABLE_IP = \"10.11.99.1\"              # reMarkable IP address\nREMARKABLE_USER = \"root\"                   # SSH username\nREMARKABLE_TEMPLATES_DIR = \"/usr/share/remarkable/templates\"\nREMARKABLE_DEFAULT_CATEGORY = \"Custom\"     # Default category for new templates\nREMARKABLE_SSH_KEY = \"~/.ssh/id_rsa\"      # SSH private key path\n```\n\n## Image Requirements\n\nThe tool automatically converts your images to meet reMarkable's specifications:\n\n- **Resolution**: 1872×1404 pixels\n- **DPI**: 226\n- **Format**: Grayscale PNG\n- **Supported Input**: PNG, JPG, JPEG, WebP\n\n## File Structure\n\n```\nrm2-templater/\n├── converted/          # Converted PNG files (temporary)\n├── backups/           # Automatic backups of templates.json\n├── templates.json     # Local copy of reMarkable's template registry\n└── src/rm2_templater/\n    ├── cli.py         # Main CLI interface\n    ├── settings.py    # Configuration\n    ├── Template.py    # Data models\n    ├── convert_image.py   # Image processing\n    └── ensure_ssh_key.py  # SSH key management\n```\n\n## How It Works\n\n1. **SSH Connection**: Uses SSH to securely connect to your reMarkable\n2. **Image Processing**: Converts images to reMarkable's required format using Pillow\n3. **File Upload**: Transfers converted PNGs to `/usr/share/remarkable/templates/Custom/`\n4. **Registry Update**: Updates `templates.json` with new template metadata\n5. **UI Restart**: Restarts the reMarkable UI (`xochitl`) to load new templates\n\n## Safety Features\n\n- **Automatic Backups**: Creates timestamped backups before any changes\n- **Idempotent Operations**: Safe to run multiple times\n- **Confirmation Prompts**: Asks before destructive operations\n- **Error Handling**: Graceful handling of network and file system errors\n\n## Troubleshooting\n\n### Connection Issues\n\n**Problem**: `Authentication failed` error\n\n```bash\n# Solution: Re-run SSH setup\nrm2 setup-ssh\n```\n\n**Problem**: `Connection timeout`\n\n- Ensure your reMarkable is awake and connected to the same network\n- Verify the IP address in Settings \u003e Help \u003e GPLv3 Compliance\n- Check that SSH is enabled (it should be by default)\n\n### Template Issues\n\n**Problem**: Templates don't appear after adding\n\n```bash\n# The UI restart should happen automatically, but you can manually restart:\nssh root@\u003cremarkable-ip\u003e \"systemctl restart xochitl\"\n```\n\n**Problem**: Image quality issues\n\n- Ensure your source images are high resolution\n- The tool converts to grayscale automatically\n- Templates work best with simple line art and text\n\n## Inspiration\n\nThis tool was inspired by the excellent tutorials from [Simply Kyra](https://www.simplykyra.com/):\n\n- [Learn How to Access Your reMarkable Through the Command Line](https://www.simplykyra.com/blog/learn-how-to-access-your-remarkable-through-the-command-line/)\n- [How to Make Template Files for Your reMarkable](https://www.simplykyra.com/blog/how-to-make-template-files-for-your-remarkable/)\n\n## Requirements\n\n- Python 3.13+\n- reMarkable 2 tablet\n- Network connection between your computer and reMarkable\n\n## Dependencies\n\n- `typer` - CLI framework\n- `paramiko` - SSH client\n- `pillow` - Image processing\n- `pydantic` - Data validation\n- `loguru` - Logging\n\n## License\n\nThis project is open source. Please check the license file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n---\n\n**Note**: This tool modifies system files on your reMarkable. While it includes safety measures like automatic backups, use at your own risk. Always ensure your reMarkable is backed up before making changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrader%2Frm2-templater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrader%2Frm2-templater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrader%2Frm2-templater/lists"}