InkJet - Bluetooth Thermal Printer

Print text, images, and QR codes to a wireless Bluetooth thermal printer from a MacOS device. Use inkjet print for output, inkjet scan to discover printers.

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

bash

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.

bash

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.

bash

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.

bash

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).

bash

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

Print Images

bash

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.

bash

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

Paper Control

bash

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).

bash

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.

json

{"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.

bash

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.

bash

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).

bash

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 \n\n\n 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:

bash

inkjet doctor             # Diagnose connection issues