| name | print-label |
| description | Print a label on a registered printer at a chosen media size, with an optional second line. Previews first when the layout is uncertain. |
Print a label
Works against the registry that profile-printers built, so it is
printer-agnostic: pick a printer by id, or let it pick when only one is
registered.
Before printing
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/labelctl.py" registry list
If the registry is empty, run profile-printers first — do not guess an
address.
Preview, then print
preview never opens a socket to the printer. That separation is
load-bearing: brother_ql print converts and transmits in one step with no
dry-run flag, so the only safe way to see a label before spending media is to
render it and stop.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render.py" preview \
--text "Spare fuses" --subtext "Garage shelf B" --printer ql-810w -o /tmp/label.png
Read the PNG back and look at it when the layout is uncertain — a long heading,
non-Latin text, or an unfamiliar media size. For routine labels skip straight to
printing; a preview the user did not ask for is a round trip they did not want.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render.py" print \
--text "Spare fuses" --subtext "Garage shelf B" --printer ql-810w --copies 2
Both commands print a JSON object with a printed field. printed: false means
nothing was sent — do not report a preview as a completed print.
Choosing the media size
The canvas comes from the printer's installed_media, so normally you pass
nothing. Override with --media only when the user has physically changed the
roll, and record it afterwards so the next print is right too:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/labelctl.py" media list
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/labelctl.py" media show DK-11202
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/labelctl.py" registry set-media --id ql-810w --media DK-11202
Two geometries behave differently and it is worth saying which the user is on:
- Continuous roll (
DK-22210, all TZe) — the label grows to fit the text,
capped at 90 mm. You choose the length by choosing the words.
- Die-cut (
DK-11202, DK-11201, the round ones) — the length is fixed by
the label itself. Text shrinks to fit; it cannot overflow onto the next one.
An installed_media that does not match the physical roll produces a
wrong-sized label, not an error. If a print comes out visibly misaligned,
suspect that before suspecting the printer.
Judgement
- Confirm before more than a few copies. Media is consumable and no Brother
label printer reports how much is left. Above 5 copies, say what is about to
print and get a yes. The renderer refuses more than 20 outright.
- Ask before printing a placeholder. A heading that is obviously a stand-in,
or a QR pointing at
example.com, is a label that has to be redone. One
question is cheaper than one wasted label.
- Do not loop this for a batch. Several different labels is one call each,
and that is fine, but tell the user the total first.
- Two-line labels need height. Below roughly 18 mm the second line is
dropped rather than rendered illegibly. On 12 mm tape, put everything in
--text.
- For a QR label see
qr-labels; for something printed repeatedly see
label-templates.
When it fails
print returns the backend's exit code and stderr. Common causes, in the order
worth checking:
| Symptom | Usually means |
|---|
| network printer, connection refused | asleep or off the LAN — discover reports raw_port_9100 |
| USB P-touch not found | auto-powered-off; it cannot be woken over USB, someone must press the button |
| job accepted, nothing emerges | roll ran out, or the cover is open |
LIBUSB_ERROR_ACCESS | user not in the lp group — see install-drivers |
deprecation warning: brother_ql.devicedependent | noise, not a failure; it appears on successful jobs too |
printer-troubleshooting goes further. Note that a reachable printer says
nothing about whether it has media — reachability is a TCP connect, and the
printer has no ink to run out of, so a failed print on a reachable printer is
almost always the roll or the cover.
