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 \n escape sequences for multiline output. No emojis.
inkjet print text "Hello, World!"
inkjet print text "Line 1\nLine 2\nLine 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\n- 1x Coffee\n- 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 <UUID> # Set default device
inkjet config set energy 12000 # Set darkness (local project)
inkjet config alias kitchen <UUID> # 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:
- Size for Visibility: Use
## headers — standard text is too small for kids to read/write comfortably
- Manual Numbering: Avoid Markdown lists (
1. content) — they auto-indent and waste horizontal space. Use ## 1) 5 + 2 = ___
- Cheap Paper Rule: Use
\n\n\n between items — thermal paper is free, give writing room
- 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
