inkjet 0.1.2

CLI tool for Bluetooth thermal printer control and printing

🖨️ inkjet — Thermal Printer CLI

The physical terminal for agents. Zero ink. Pennies per print.

inkjet is a CLI control plane for inexpensive X6H/cat toy style Bluetooth thermal printers. Its designed for humans and agentic workflows that require high-frequency physical output without the overhead of proprietary ink, drivers, or "Low Cyan" warnings.

Install • Quickstart • Why inkjet? • Claude Skill

---

Why inkjet?

1. The Name is Ironic

Traditional inkjet printers are a nightmare of DRM-locked cartridges, clogged heads, and expensive maintenance. inkjet has zero ink. It uses heat, cheap thermal paper, and code.

2. Agentic Economics

If your AI agent prints 50 status updates, debug logs, or "receipts of thought" per day, a standard printer would bankrupt you. Thermal paper costs practically nothing. inkjet enables a high-bandwidth, ultra-low-cost physical signaling channel for local AI.

3. Machine First

While most thermal printer apps are locked behind buggy mobile UIs, inkjet provides a clean, scriptable interface.

---

Install

via pip

pip install inkjet

via Homebrew (macOS)

brew install aaronchartier/tap/inkjet

Note for macOS Users

On the first run, macOS will display a system dialog asking for Bluetooth Access.

1. Click Allow.
2. If the first command failed with an error, simply run it again—it will succeed now that permissions are granted.
3. Ensure Bluetooth is toggled ON in System Settings.

Note for Everyone Else

Unfortunately I cannot guarantee support for other OSes(es) at this time. Hope that changes soon - happy tinkering!

---

Quickstart

Preparation: Ensure your printer is ON. Note that the printer does NOT need to be paired to your computer's Bluetooth settings; inkjet connects directly via BLE.

# 1. Discover and auto-configure your printer
inkjet scan

# 2. Print something immediately
inkjet print text "Ship it." --size 48

# 3. Verify configuration
inkjet whoami

---

Usage

General

• About: inkjet about (Show project credits and version)
• Status: inkjet whoami (Show current configuration)
• Doctor: inkjet doctor (Diagnose connection issues)

Printing

• Text: inkjet print text "Hello" (supports --size, --font, and stdin via -)
• Images: inkjet print image ./photo.png (auto-dithering for thermal media)
• QR Codes: inkjet print qr "https://github.com/AaronChartier/inkjet"
• Stdin: echo "Agent log..." | inkjet print text -

Configuration

• Scan: inkjet scan (discovers printers and identifies aliases)
• Settings: inkjet config set energy 12000 (adjust darkness)
• Layout: inkjet config set padding_top 20 (manage margins/spacing)
• Aliases: inkjet config alias den "15F8CC20-..." (save friendly names)
• Default: inkjet config set printer <UUID> (shortcut for setting the default device)

Configuration Schema (JSON)

Agents can modify behavior by writing directly to ~/.inkjet/config.json or ./.inkjet/config.json:

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

Smart Configuration (Local-First)

By default, inkjet saves settings to ~/.inkjet/config.json. However, it supports a Local-First workflow ideal for specific projects or agents:

• Prioritization: If a ./.inkjet/config.json exists in your current folder, inkjet will use it instead of the global one.
• Portability: Force a local config using the --local flag:
  • inkjet config set energy 5000 --local
  • inkjet scan --local
• Verification: Use inkjet doctor to see exactly which config file is currently active.

Paper Control

• Feed: inkjet feed 100 (manual advance)

---

Claude Skill

inkjet is built to be a "Claude Skill." By adding the inkjet binary to your environment, you give your AI agents the ability to:

• Print physical status receipts for long-running tasks.
• Output QR codes for mobile handoffs (e.g., "Scan this to see the URL I just generated"). QR codes are ligible down to size 75.
• Create physical "ticketing" systems for Jira or GitHub issues.

See SKILL.md for the full agentic instruction set.

---

Supported Hardware

inkjet is built for those $5 'Got-It-Online' thermal printers (Cat Printers, Mini Pocket Printers, etc).

Specifically, any printer using the X6H, GT01, or MX06 Bluetooth protocols. These are the gold standard for budget agentic output: they are small, battery-powered, and use standard 58mm thermal rolls that cost next to nothing. Personally tested working with X6H.

---

Technical Protocol (for tinkerers)

inkjet communicates via Bluetooth Low Energy (BLE) using the industry-standard GATT write-point for this hardware family:

• Service UUID: 0000AE01-0000-1000-8000-00805F9B34FB
• Characteristic UUID: 0000AE01-0000-1000-8000-00805F9B34FB

If you encounter a new "mystery" printer that doesn't work out of the box, use a mobile BLE scanner like nRF Connect to check if your device exposes the AE01 service. If it uses a different characteristic, please open an issue!

---

License

MIT