Thermal Printer Skill

Print text, images, and QR codes to cheap Bluetooth thermal printers (X6h, GT01, cat printers) via inkjet CLI. Thermal paper is extremely low-cost, enabling high-frequency physical output. No emojis in print content.

Install

inkjet --version           # Check if already installed; skip install if this succeeds
pip install inkjet         # Universal
brew install aaronchartier/tap/inkjet  # macOS (takes longer, compiles Pillow)

Setup

Printer must be ON but does NOT need Bluetooth pairing — inkjet connects directly via BLE.

inkjet scan               # Discover printers, set default
inkjet whoami             # Check current configuration

Print Text

Print strings directly. Supports \ escape sequences for multiline output. No emojis.

inkjet print text "Hello, World!"
inkjet print text "Line 1\
Line 2\
Line 3"
inkjet print text "Big Text" --size 72

Print Markdown

Render high-fidelity formatted content using Markdown syntax. Recommended way for agents to output complex receipts or logs without saving temporary files. No emojis.

inkjet print text "# Order 104\
- 1x Coffee\
- 1x Donut" --markdown

Print Files

Output contents of a local file. Supports plain text (.txt) and Markdown (.md).

inkjet print file ./receipt.txt
inkjet print file ./README.md

Print Images

inkjet print image ./photo.png
inkjet print image ./logo.jpg --dither

Print QR Codes

Generates and prints QR codes. Smartphone scanners reliably read codes down to --size 75.

inkjet print qr "https://github.com/AaronChartier/inkjet"
inkjet print qr "WiFi:S:NetworkName;P:example123;;" --size 75

Paper Control

inkjet feed 100           # Feed paper forward (steps)

Configuration

Manage settings globally or per project. If .inkjet/ exists in current workspace, it takes priority over global config (use --local to create).

inkjet config show                    # Show all settings
inkjet config set printer \x3CUUID>      # Set default device
inkjet config set energy 12000        # Set darkness (local project)
inkjet config alias kitchen \x3CUUID>    # Save a friendly name

Config JSON Schema (direct filesystem edit)

Bypass CLI and modify behavior by writing directly to config JSON. Priority: ./.inkjet/config.json > ~/.inkjet/config.json. Use this to adjust default margins, alignment, or font sizes for different document types without changing command strings.

{"default_printer":"UUID","printers":{"alias":"UUID"},"energy":12000,"print_speed":10,"quality":3,"padding_left":0,"padding_top":10,"line_spacing":8,"align":"left","font_size":18}

Multi-Printer Orchestration

If the environment (e.g., TOOLS.md) contains multiple printer UUIDs or aliases, target specific hardware with --address / -a. Use -a default for primary device.

inkjet print text "Main Status" -a office      # Role-based routing
inkjet print text "Order #104" -a kitchen
inkjet print qr "https://example.com" -a default
inkjet print file ./log.txt -a "UUID_EXT_1"    # Direct UUID targeting

Strategies: Role-Based Routing (route content by hardware role, e.g. stickers vs receipts) or Load Balancing (round-robin across printer farm for max prints-per-minute).

Piping Content (stdin)

Stream data from another command's output without creating temp files. Use - to read from stdin.

echo "Receipt line 1" | inkjet print text -    # Text piping
curl -s "https://example.com/logo.jpg" | inkjet print image -  # Image piping

JSON Output

Commands support --json for machine-readable output (useful for scripting).

inkjet scan --json
inkjet whoami --json

Worksheet Best Practices

Thermal paper is narrow and cheap. For children's worksheets or handwriting:

1. Size for Visibility: Use ## headers — standard text is too small for kids to read/write comfortably
2. Manual Numbering: Avoid Markdown lists (1. content) — they auto-indent and waste horizontal space. Use ## 1) 5 + 2 = ___
3. Cheap Paper Rule: Use \ \ \ between items — thermal paper is free, give writing room
4. Tear-off Line: End with --- for a clean tear-off that doesn't cut off the last problem

Troubleshooting

If printer not found:

inkjet doctor             # Diagnose connection issues