playbooks

home / skills / desplega-ai / ai-toolbox / remarkable-expert

remarkable-expert skill

/cc-plugin/remarkable/skills/remarkable-expert

This skill helps you manage reMarkable files with rmapi, enabling listing, downloading, uploading, and organizing content on your tablet.

npx playbooks add skill desplega-ai/ai-toolbox --skill remarkable-expert

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.9 KB
---
name: remarkable-expert
description: reMarkable tablet expert. Use when users want to list, download, or upload files to their reMarkable tablet.
---

# reMarkable Expert

You are an expert on managing files on a reMarkable tablet using `rmapi`.

## Prerequisites

- `rmapi` must be installed at `~/.local/bin/rmapi` and authenticated
- For uploads: `pandoc` is required for markdown conversion

## Quick Reference

| Command | Description |
|---------|-------------|
| `rmapi ls [path]` | List files in folder (default: root) |
| `rmapi get <path>` | Download file as `.rmdoc` (zip archive) |
| `rmapi put <local> [remote]` | Upload file to tablet |
| `rmapi mkdir <path>` | Create folder |
| `rmapi find <dir> [pattern]` | Find files recursively |

## File Format Reality

All files download as `.rmdoc` (a zip archive). What's inside depends on the file type:

| Original Type | Contents of .rmdoc | How to View |
|---------------|-------------------|-------------|
| **Uploaded PDF** | `.pdf` + `.content` + `.metadata` | Extract the `.pdf` from zip |
| **Native notebook** | `.rm` strokes + `.content` + `.metadata` | No good local converter exists |

**Important:** `rmapi geta` (annotation export) is currently broken - it generates empty 490-byte PDFs.

## Common Workflows

### List Files
```bash
rmapi ls           # Root folder
rmapi ls Books     # Specific folder
```

Output format: `[f]` = file, `[d]` = folder

### Download and View a PDF
```bash
# 1. Download (creates <name>.rmdoc)
rmapi get "Books/MyBook.pdf"

# 2. Check if it contains a PDF
unzip -l "MyBook.pdf.rmdoc" | grep "\.pdf$"

# 3. Extract the PDF
unzip -j "MyBook.pdf.rmdoc" "*.pdf" -d /tmp/

# 4. Open it
open /tmp/*.pdf
```

### Download Native Notebook
Native notebooks (handwritten notes without a source PDF) only contain `.rm` stroke data. There's no reliable local converter - options:
1. Export from tablet via Share menu
2. Use reMarkable desktop app
3. Connect USB and use web interface at `http://10.11.99.1`

### Upload Markdown as PDF
```bash
pandoc document.md -o /tmp/document.pdf
rmapi put /tmp/document.pdf "Documents/"
```

### Upload PDF Directly
```bash
rmapi put report.pdf "Work/"
```

## File Types on Tablet

| What you see | Actually stored as | Viewable locally? |
|--------------|-------------------|-------------------|
| Uploaded PDF | PDF inside .rmdoc | Yes - extract from zip |
| Web article | Native notebook | No - needs converter |
| Handwritten notes | Native notebook | No - needs converter |
| ePub | Converted internally | Partial |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Unauthorized" | Re-authenticate: `rmapi` (get new code from my.remarkable.com) |
| File not found | Use `rmapi ls` to check exact path and name |
| Upload fails | Check file size (<100MB for cloud) |
| Empty/corrupt PDF from geta | Known bug - extract PDF from .rmdoc instead |
| Can't view notebook | Native format - export from tablet or use desktop app |

Overview

This skill is a reMarkable tablet expert that helps list, download, and upload files using rmapi. It documents common commands, file format behavior, and practical workflows for handling PDFs, native notebooks, and markdown-to-PDF uploads. Use it when you need reliable, repeatable steps to manage content on a reMarkable device.

How this skill works

The skill relies on the command-line tool rmapi installed at ~/.local/bin/rmapi and assumes it is authenticated. It explains how rmapi lists folders, downloads .rmdoc archives, extracts embedded PDFs, uploads files, and creates folders. For markdown uploads it uses pandoc to convert to PDF before calling rmapi put.

When to use it

  • List files and folders on your reMarkable tablet (rmapi ls).
  • Download a document to view or extract the embedded PDF from a .rmdoc archive.
  • Upload PDFs or converted markdown to the tablet (rmapi put).
  • Create folders on the device or check exact remote paths (rmapi mkdir, rmapi ls).
  • Troubleshoot common errors like authorization or missing files.

Best practices

  • Ensure rmapi is installed at ~/.local/bin/rmapi and re-authenticated before use.
  • Convert markdown to PDF with pandoc locally, then upload the PDF rather than trying to upload raw markdown.
  • When downloading, inspect the .rmdoc zip and extract the .pdf file to view locally.
  • Use rmapi ls to confirm exact path and name to avoid file-not-found errors.
  • Keep uploads under cloud size limits (commonly <100MB) and check network/authorization issues first.

Example use cases

  • Download a purchased PDF from Books, extract the PDF, and open it on your laptop.
  • Convert a project README.md to PDF with pandoc and upload it to Documents/ for reading on the tablet.
  • List a folder’s contents to find the exact remote filename before running rmapi get or put.
  • Create a new folder on the tablet for a course, then upload lecture PDFs into that folder.
  • Recover a PDF when rmapi geta produces empty exports by extracting the PDF from the .rmdoc archive.

FAQ

Why do downloaded files come as .rmdoc?

.rmdoc is a zip archive the reMarkable uses; it contains the original PDF (if present), .content and .metadata. Extract the PDF from the .rmdoc to view locally.

How do I upload markdown files?

Convert markdown to PDF with pandoc (pandoc document.md -o /tmp/document.pdf) and then upload the PDF with rmapi put.

What if rmapi geta exports empty PDFs?

This is a known issue. Instead download the .rmdoc and extract the embedded PDF, or export directly from the tablet or desktop app.