A simple, clean CLI tool to interact with your Supernote device.

• Python 3.8.1+
• Supernote device connected to same local network
• Device must have "Export via LAN" enabled (Settings → System → Export via LAN)

PDF conversion requires the Cairo graphics library. Install it before installing supynote:

macOS:

brew install cairo pkg-config

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y libcairo2-dev pkg-config python3-dev

Windows: No additional dependencies needed (pre-built wheels available)

• OCR: Requires additional dependencies (transformers, torch) - see Installation
• Apple Silicon: OCR automatically uses MPS acceleration on M1/M2/M3/M4 Macs

• 🔍 Auto-discovery: Automatically find your Supernote on the network
• 📂 File listing: Browse files and directories on your device
• ⬇️ Download: Download individual files or entire directories
• 📄 PDF conversion: Convert .note files to high-quality vector PDFs
• 🌐 Web interface: Open the device web interface in your browser
• ⚡ Fast downloads: Multithreaded downloads for speed

# Basic installation
pip install supynote

# With OCR features
pip install supynote[ocr]

# Clone and install
git clone https://github.com/thopiax/supynote.git
cd supynote
pip install -e .

# With OCR features
pip install -e .[ocr]

uv sync  # Installs all dependencies including dev tools

# Find your Supernote device
supynote find

# List all files
supynote list

# List files in Note directory
supynote list Note

# Download Note directory
supynote download Note

# Download a specific file
supynote download Note/my-note.note

# Convert .note file to PDF (vector format)
supynote convert my-note.note

# Convert all .note files in a directory
supynote convert Note/

# Open device web interface
supynote browse

# Show device info
supynote info

Before using supynote, ensure your Supernote device is ready:

1. On your Supernote: Swipe down from the top to open the menu
2. Activate "Browse & Access" (middle top icon)
3. Ensure your computer is connected to the same network
4. Only one Supernote device should have "Browse & Access" active

Now you can run supynote find to locate your device.

• Use default note names: Supernote's automatic timestamp naming (YYYYMMDD_HHMMSS) allows notes to be grouped by day, creating a journal-like structure
• Markdown extraction: Structure your notes with specific patterns for better markdown output (see Markdown Integration)

Scan the local network to find your Supernote device.

• --open: Open the device web interface after finding it

List files and directories on the device.

Download files or directories from the device.

• --workers N: Number of parallel download workers (default: 4)
• --convert-pdf: Automatically convert downloaded .note files to PDF

Convert .note files to PDF format (vector by default).

• --output DIR: Output directory or specific file path
• --no-vector: Use raster format instead of vector
• --no-links: Disable hyperlinks in PDF output
• --recursive: Process subdirectories (default: true)

Open the device web interface in your default browser.

Show device connection information.

• --ip IP: Manually specify device IP address
• --port PORT: Device port (default: 8089)
• --output DIR: Local output directory for downloads

Configure supynote-cli behavior with these environment variables:

• SUPYNOTE_JOURNALS_DIR: Default directory for markdown journal exports (used by merge command)
• SUPYNOTE_IP: Default device IP (alternative to --ip flag)
• SUPYNOTE_OUTPUT_DIR: Default output directory (alternative to --output flag)

Example .env file:

SUPYNOTE_JOURNALS_DIR=$HOME/Documents/journals
SUPYNOTE_IP=192.168.1.100

Load with: export $(cat .env | xargs)

See examples/automation/.env.example for more configuration options.

# Find device and open in browser
supynote find --open

# Download with custom output directory
supynote download Note --output ~/my-notes

# Use specific IP address
supynote --ip 192.168.1.100 list

# Download with more workers for speed
supynote download EXPORT --workers 8

# Download and convert to PDF in one step  
supynote download Note --convert-pdf

# Convert with custom output directory
supynote convert Note/ --output ~/my-pdfs

# Convert single file with specific output name
supynote convert my-note.note --output my-document.pdf

Supynote can extract text from your .note files and organize them into markdown format for daily journaling workflows. The extraction recognizes specific patterns you can optionally use while writing:

As a personal preference, you can start pages with "moment markers" to create section headings:

• Pattern: m. 1, M. 2, me 3 (case insensitive, with or without dot)
• Can be preceded by - (e.g., - m. 5)

Example on Supernote:

m. 7 - Morning thoughts about the project

Becomes in markdown:

- ## m. 7
    - Morning thoughts about the project

This is entirely optional - use it if it fits your note-taking style.

Lines starting with - or * are converted to indented bullet points.

Lines starting with ↳ become nested sub-bullets (indented one level deeper).

Using the merge command with timestamp-named files (YYYYMMDD_HHMMSS):

• Groups all notes from the same day
• Creates one markdown file per day (e.g., 2024-01-15.md)
• Orders moments chronologically within each day
• Links to the corresponding merged PDF

This creates a date-based journal structure ideal for markdown-based note-taking tools.

• Error: "cairo not found" or "pycairo build failed"
  • Install Cairo system dependencies (see System Dependencies section above)
  • macOS: brew install cairo pkg-config
  • Linux: sudo apt-get install libcairo2-dev pkg-config python3-dev
• After installing Cairo, reinstall supynote: pip install --force-reinstall supynote

• Ensure device is on same network as computer
• Try manually specifying IP: supynote --ip YOUR_IP list
• Some networks block device discovery - use --ip flag with your device's IP address

• Install OCR dependencies: pip install -e .[ocr]
• First run downloads ML models (~500MB) - may take time
• Requires internet connection for initial model download
• On Apple Silicon, ensure MPS is available (macOS 12.3+)

• Increase workers: supynote download --workers 30
• Use async mode (default in v1.0+)
• OCR is CPU/GPU intensive - fewer workers may help on older machines
• Check network connection quality

• Ensure output directory is writable
• On macOS, you may need to grant Terminal full disk access
• Check firewall settings aren't blocking network discovery

For more help, see GitHub Issues

MIT License - see LICENSE file for details.

Contributions welcome! See CONTRIBUTING.md for guidelines.

Steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

• Supernote Team: For creating excellent e-ink tablets that inspire tools like this
• supernotelib: Unofficial library for .note file conversion - the foundation of PDF conversion in this tool
• Claude Code: This project was built with significant assistance from Claude Code, which handled much of the heavy lifting in development and refactoring
• TrOCR (Microsoft) and LLaVA: Powering the OCR capabilities for handwritten text recognition