python-escpos-cli Skill

An AI skill for controlling ESC/POS thermal receipt printers from the command line using the python-escpos CLI.

What This Skill Does

This skill teaches an AI agent (or serves as a human reference) how to:

• Install python-escpos and its dependencies (pyusb, libusb, Pillow, etc.)
• Identify a connected thermal printer (USB, serial, network, file, LP, CUPS, Win32Raw)
• Configure a config.yaml file for any of the 8 supported printer types
• Print text, barcodes, QR codes, images, and cut paper, all from the shell
• Troubleshoot common issues and known bugs in v3.1

It was built from the context7 llms.txt documentation, verified against the actual CLI source code (cli.py), and tested on physical hardware (Epson TM-m30II, USB).

Supported Printers

Type	Config type	Use Case
USB	usb	Direct USB connection (most common)
Serial	serial	RS-232 serial port
Network	network	TCP/IP (port 9100)
File	file	Raw device node (/dev/usb/lp0)
Dummy	dummy	Testing without hardware
LP	lp	CUPS via lp command
CUPS	cupsprinter	CUPS server
Win32Raw	win32raw	Windows raw printing

Tested on: Epson TM-m30II (USB 0x04b8:0x0e2a), python-escpos 3.1, macOS 14.6.

Compatibility Matrix

This table holds only what the README and SKILL.md already claim. "Not tested" means the repo documents the interface, but no print on hardware was confirmed.

Printer model	Interface	Result	Notes
Epson TM-m30II (0x04b8:0x0e2a)	USB (usb)	Working, tested	Tested on physical hardware with python-escpos 3.1 on macOS 14.6. This model has no capabilities profile, so use profile: default.
Epson TM-m30II	CUPS (cupsprinter) or LP (lp)	Not tested	The skill documents a CUPS-listed EPSON_TM_m30II queue as usable even when the printer is offline. No print on this interface was confirmed.
Epson TM-T20, TM-T88, TM-TIII series	Any (usb, serial, network)	Not tested	Named as target models. The capabilities DB has the profiles TM-T20II, TM-T88II, TM-T88III, TM-T88IV, TM-T88V.
Star Micronics printers	Any	Not tested	Named as target models only. No profile and no test claim.
Any ESC/POS printer	Dummy (dummy)	No output	Preview and test path without hardware.
Any ESC/POS printer	Serial (serial), Network (network), File (file), Win32Raw (win32raw)	Not tested	Documented config types. No hardware test claim for these interfaces.
Any ESC/POS printer	CLI commands fullimage, demo, cashdraw --pin, set --text_type, charcode --code UTF8, software_columns	Broken in v3.1	Command level, not model level, so it applies to every printer. Details and workarounds: Known Bugs in v3.1.
Any ESC/POS printer	CLI commands text, block_text, qr, barcode, image, cut, set (without --text_type), hw, control, panel_buttons, raw, charcode (with CP* names), version, version_extended	Working	Confirmed on v3.1.

CLI Commands Covered

Command	Status	Description
text	✅ Working	Print plain text
block_text	✅ Working	Print word-wrapped text
qr	✅ Working	Print a QR code
barcode	✅ Working	Print barcodes (EAN13, CODE128, UPC, etc.)
image	✅ Working	Print bitmap images (bitImageRaster, bitImageColumn, graphics)
cut	✅ Working	Cut paper (FULL or PART)
set	✅ Partial	Set text alignment/size/density (align/width/height work; --text_type is broken)
hw	✅ Working	Hardware operations (INIT, SELECT, RESET)
control	✅ Working	Control sequences (LF, FF, CR, HT, VT)
panel_buttons	✅ Working	Enable/disable feed button
raw	✅ Working	Send raw ESC/POS bytes
charcode	✅ Working	Set character code page
fullimage	❌ Broken	KeyError in v3.1: use image instead
software_columns	❌ N/A	Not in v3.1 release
demo	❌ Broken	Argparse filtering bug crashes all modes
cashdraw	❌ Broken from CLI	Argparse type mismatch: use Python API
version	✅ Working	Print version
version_extended	✅ Working	Diagnostics + driver usability

Quick Start

1. Install

pip install python-escpos[all]

# macOS USB support
brew install libusb
pip install pyusb

# Linux USB support
sudo apt-get install libusb-1.0-0-dev
pip install pyusb

2. Identify your printer

# macOS
system_profiler SPUSBDataType | grep -B2 -A8 "0x04b8"

# Linux
lsusb

Look for the Vendor ID and Product ID (e.g. 0x04b8:0x0e2a for Epson TM-m30II).

3. Create config

mkdir -p ~/Library/Application\ Support/python-escpos  # macOS
# or: mkdir -p ~/.config/python-escpos                  # Linux

Create config.yaml:

printer:
  type: usb
  idVendor: 0x04b8
  idProduct: 0x0e2a
  profile: default

4. Print

python-escpos text --txt "Hello World"
python-escpos qr --content "https://example.com" --size 6
python-escpos barcode --code 4006381333931 --bc EAN13 --height 64 --width 2
python-escpos cut --mode FULL

Known Bugs in v3.1

Bug	Workaround
set --text_type → TypeError	Use raw --msg "\x1bE\x01" for bold, or Python API p.set(bold=True)
fullimage → KeyError	Use image --img_source instead
demo → BarcodeCodeError	Don't use demo; test individual commands
cashdraw --pin → invalid choice	Use python3 -c "from escpos.printer import Usb; p=Usb(0x04b8,0x0e2a); p.cashdraw(2)"
charcode --code UTF8 → KeyError	Only CP* names valid: CP437, CP858, CP1252, etc.
text --txt '---' → argparse error	Any value starting with - breaks argparse. Use =, ., or _ separators

How to Install This Skill

For AI agent harnesses that use ~/.agents/skills/

# Clone the repo
gh repo clone faramirezs/python-escpos-cli-skill ~/.agents/skills/python-escpos-cli

The skill is auto-discovered on the next agent session. The trigger keywords are in the description frontmatter field.

For Hermes-agent / other skill systems

Copy SKILL.md into your skills directory following your harness's conventions. See the hermes-agent-skill-authoring docs for in-repo skill placement.

File Structure

.
├── SKILL.md      # The skill (frontmatter + full documentation)
└── README.md     # This file

Sources

• context7: https://context7.com/python-escpos/python-escpos/llms.txt
• CLI source (verified): src/escpos/cli.py from python-escpos v3.1
• Config source (verified): src/escpos/config.py
• Capabilities DB: https://github.com/escpos/escpos-printer-db
• Official docs: https://python-escpos.readthedocs.io/
• Hardware tested: Epson TM-m30II (USB 0x04b8:0x0e2a)

License

MIT: same as python-escpos itself.