| name | remarkable-upload |
| description | Upload Markdown and source files to a reMarkable device as PDFs using the remarquee CLI (rmapi-backed). Use when the user asks to upload/send/export docs/examples to reMarkable, bundle multiple files into one PDF with a ToC, choose an /ai/YYYY/MM/DD destination, avoid or force overwrites, or troubleshoot pandoc/xelatex/rmapi auth. |
Remarkable Upload
IMPORTANT: Minimize tool calls
Remarquee operations are expensive in agent sessions. Follow these rules strictly:
- Never run
remarquee status before uploading. The upload command itself will fail clearly if something is wrong. Just run the upload directly.
- Never run
remarquee cloud ls to verify after a successful upload. If the upload prints OK: uploaded <name> -> <path>, it succeeded. Only check cloud ls if the upload fails AND you need to understand why.
- Never run
remarquee cloud account to check auth before uploading. Upload commands now auto-retry with reauth on 401/403 — you do NOT need to handle auth expiry manually. If you see NOTE: auth expired, re-authenticating and retrying... in stderr, just let it proceed.
- Do NOT call
remarquee upload --help or remarquee cloud --help. The command reference below has all the flags you need.
Typical workflow (2 calls max, not 5)
Normal upload:
remarquee upload bundle <path...> --name "<doc name>" --remote-dir "/ai/YYYY/MM/DD/<folder>" --toc-depth 2 --non-interactive 2>&1
That's it. One call. If it succeeds (output contains "OK: uploaded"), you're done. No verification step needed.
If upload fails with auth error despite auto-retry (the NOTE: auth expired message appears but the retry also fails):
remarquee upload bundle <path...> --name "<doc name>" --remote-dir "/ai/YYYY/MM/DD/<folder>" --toc-depth 2 --reauth --non-interactive 2>&1
This is rare — the auto-retry handles normal token expiry. Only use --reauth manually if the auto-retry also fails.
If you need to check what's already on the device (e.g. to decide --force):
remarquee cloud ls /ai/YYYY/MM/DD/<folder> --long --non-interactive 2>&1
Only do this when you genuinely need to know existing state, never as a routine post-upload check.
Command reference
Upload commands
| Command | When to use | Key flags |
|---|
remarquee upload bundle | Multiple .md files → one PDF with ToC | --name, --remote-dir, --toc-depth, --force, --date, --non-interactive, --reauth, --dry-run |
remarquee upload md | Single or multiple .md files → separate PDFs | --name, --remote-dir, --force, --date, --non-interactive, --reauth, --dry-run, --flatten |
remarquee upload src | Source code files → syntax-highlighted PDFs | --name, --remote-dir, --force, --date, --non-interactive, --reauth, --dry-run, --bundle, --include-ext |
Common flags
--name "<title>" — Document name (use simple names: no special chars, no colons, no parens). The PDF filename is auto-sanitized.--remote-dir "/ai/YYYY/MM/DD/<folder>" — Full remote path override--date YYYY/MM/DD — Sets date portion of remote path (default: today)--force — Overwrite existing document (WARNING: deletes existing + annotations)--non-interactive — Required for agent sessions (don't prompt for codes)--reauth — Force re-authentication when tokens are stale--dry-run — Preview what would happen without running pandoc or uploading--toc-depth N — ToC depth for bundle (default: 1)
Cloud commands
| Command | When to use | Key flags |
|---|
remarquee cloud ls <path> | List files on device | --long, --non-interactive |
remarquee cloud account | Check auth status | --non-interactive, --reauth |
remarquee cloud get <path> | Download a document | --out-dir, --non-interactive |
remarquee cloud search <query> | Search by name | --match name, --limit, --compact, --non-interactive |
remarquee cloud rm <path> | Delete a document | --non-interactive |
Destination conventions
- Default remote directory:
/ai/YYYY/MM/DD/
- Ticket-aware:
/ai/YYYY/MM/DD/<TICKET-ID>/
- Always use
--non-interactive in agent sessions
Name sanitization
The CLI automatically sanitizes document names for upload:
- Spaces → underscores in PDF filenames
- Special characters that break rmapi are stripped
So you can use --name "GOJA-053 FS Module Guide" and the CLI will handle it.
Common issues
- Pandoc "Unknown alias" errors: Usually caused by malformed code block syntax. Test with
pandoc <file>.md -o /tmp/test.pdf --pdf-engine=xelatex to isolate.
- Nested code blocks in markdown: Use explicit language tags like
```markdown and ```json. Do NOT use sed to replace all ``` markers.
- 401 Unauthorized during upload: Re-run the same command with
--reauth --non-interactive added.
- 400 Bad Request during upload: Usually a filename issue — use
--name with a simple name (alphanumeric + spaces + dashes only).
