budtags/skills/zpl/SKILL.md
Use this skill when generating ZPL code, working with ZPL commands, creating Zebra printer labels, or troubleshooting ZPL syntax and formatting issues.
npx skillsauth add jwilly246/budtags-claude-plugin zplInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
You are now equipped with comprehensive knowledge of the Zebra Programming Language (ZPL II). This skill provides instant access to the complete ZPL II Programming Guide, including all commands, programming techniques, and best practices for generating Zebra printer labels.
When the user asks about ZPL programming, you can:
This skill includes the complete ZPL II Programming Guide split into 37 easily-digestible markdown files:
Complete reference for all ZPL II commands with syntax, parameters, and examples.
Getting Started:
volume-1/00-front-matter.md - Copyright, table of contentsvolume-1/01-introduction.md - Getting started with ZPL IIvolume-1/02-basic-exercises.md - 5 hands-on exercises for beginnersCommands by Category:
volume-1/03-commands-fonts.md - ^A, ^A@ font commandsvolume-1/04a-commands-barcodes-basic.md - Code 11, Code 39, Codabar, etc.volume-1/04b-commands-barcodes-upc-ean.md - UPC-A, UPC-E, EAN-8, EAN-13volume-1/04c-commands-barcodes-advanced.md - Code 93, Code 128, MSI, Plesseyvolume-1/04d-commands-barcodes-2d.md - QR Code, Data Matrix, Aztec, PDF417volume-1/04e-commands-barcodes-specialty.md - MaxiCode, RSS, POSTNET, TLC39volume-1/05-commands-config.md - Printer settings (^C* commands)volume-1/06-commands-downloads.md - Fonts, graphics, formats (^D*, ~D*)volume-1/07a-commands-fields-basic.md - ^FO, ^FD, ^FS, ^FT (basic field operations)volume-1/07b-commands-fields-advanced.md - ^FB, ^FM, ^FP, ^FR, ^FV, ^FW (text blocks, mirroring, etc.)volume-1/08-commands-graphics.md - Boxes, circles, ellipses, lines (^GB, ^GC, ^GD, ^GE, ^GF)volume-1/09-commands-host-status.md - Communication and status queriesvolume-1/10-commands-images.md - Image download and managementvolume-1/11-commands-system.md - Job control, configurationvolume-1/12-commands-labels-media.md - Label layout, media handlingvolume-1/13-commands-network.md - Network printer commandsvolume-1/14-commands-print.md - Print control, quantity, speedvolume-1/15-commands-rfid.md - RFID tag programmingvolume-1/16-commands-serial-misc.md - Serial, miscellaneous commandsvolume-1/17-back-matter.md - Index and contact informationProgramming concepts, techniques, advanced topics, and best practices.
Files:
volume-2/00-front-matter.md - Document conventions and organizationvolume-2/01-zpl-basics.md - ZPL II fundamentals and format structurevolume-2/02-programming-exercises.md - 6 progressive programming exercisesvolume-2/03a-advanced-stored-formats.md - Stored formats, serialization, variable datavolume-2/03b-advanced-control-commands.md - Advanced control techniquesvolume-2/03c-advanced-graphics-networking.md - Graphics handling and networkingvolume-2/04-fonts-barcodes.md - Font types, matrices, barcode implementationvolume-2/05-printer-configuration.md - Printer setup via ZPL IIvolume-2/06-xml-super-host-status.md - XML status reportingvolume-2/07-real-time-clock.md - RTC commands and date/time handlingvolume-2/08-mod-check-digits.md - Check digit calculation (Mod 10/43)volume-2/09-error-detection-protocol.md - Communication protocol and error handlingvolume-2/10-zb64-encoding.md - Base64 encoding for ZPLvolume-2/11-appendices.md - Character sets and reference tablesLanguage Type: Label markup language for Zebra thermal printers Version: ZPL II (Zebra Programming Language II) Primary Use: Generating thermal printer labels with text, barcodes, graphics, and RFID Execution: Sent directly to Zebra printers via serial, parallel, USB, or network connection
Key Features:
^XA // Start of label format
^FO50,50 // Field Origin (X=50 dots, Y=50 dots)
^A0N,50,50 // Font: scalable, normal orientation, height=50, width=50
^FDHello World^FS // Field Data with Field Separator
^XZ // End of label format
Key Commands:
^XA - Start label format^XZ - End label format^FO - Field Origin (positioning)^FD - Field Data (content)^FS - Field Separator (end of field)^A - Font selection^B - Barcode commands^GB - Graphic Box^GC - Graphic CircleSee: volume-2/01-zpl-basics.md for complete fundamentals
Text & Fonts:
^A commands → volume-1/03-commands-fonts.md^FB → volume-1/07b-commands-fields-advanced.md^FO, ^FT → volume-1/07a-commands-fields-basic.mdBarcodes:
volume-1/04a-04c-commands-barcodes-*.mdvolume-1/04d-commands-barcodes-2d.mdvolume-1/04b-commands-barcodes-upc-ean.mdGraphics:
volume-1/08-commands-graphics.mdvolume-1/10-commands-images.mdLabel Layout:
^LL, ^LH → volume-1/12-commands-labels-media.md^PQ → volume-1/14-commands-print.md^PR → volume-1/14-commands-print.mdAdvanced:
volume-1/15-commands-rfid.mdvolume-2/03a-advanced-stored-formats.mdvolume-2/03a-advanced-stored-formats.md| Prefix | Category | File Location | |--------|----------|---------------| | ^A* | Fonts | volume-1/03 | | ^B* | Barcodes | volume-1/04a-04e | | ^C* | Configuration | volume-1/05 | | ^D*, ~D* | Downloads | volume-1/06 | | ^F* | Fields | volume-1/07a-07b | | ^G* | Graphics | volume-1/08 | | ^H*, ~H* | Host Status | volume-1/09 | | ^I* | Images | volume-1/10 | | ^J*, ~J* | System | volume-1/11 | | ^L*, ^M* | Labels/Media | volume-1/12 | | ^N*, ~N* | Network | volume-1/13 | | ^P* | Print Control | volume-1/14 | | ^R* | RFID | volume-1/15 | | ^S*, ^T*, ^W*, ^X*, ^Z* | Serial/Misc | volume-1/16 |
^XA
^FO50,50^A0N,30,30^FDProduct Name^FS
^FO50,100^A0N,25,25^FDSKU: 12345^FS
^FO50,150^A0N,20,20^FDPrice: $29.99^FS
^XZ
^XA
^FO100,50^A0N,30,30^FDProduct Label^FS
^FO100,100^BY2^BCN,100,Y,N,N^FD123456789^FS
^XZ
See: volume-1/04c-commands-barcodes-advanced.md for Code 128 details
^XA
^FO100,50^BQN,2,4^FDQA,QR Code Data Here^FS
^FO100,250^A0N,25,25^FDScan for info^FS
^XZ
See: volume-1/04d-commands-barcodes-2d.md for QR code details
^XA
^FO50,50^A0N,30,30^FD{{ product_name }}^FS
^FO50,100^A0N,25,25^FDStrain: {{ strain_name }}^FS
^FO50,150^BY2^BCN,80,Y,N,N^FD{{ package_tag }}^FS
^FO50,250^A0N,20,20^FDTHC: {{ thc_percent }}%^FS
^FO50,280^A0N,20,20^FDCBD: {{ cbd_percent }}%^FS
^FO50,310^A0N,20,20^FDHarvest: {{ harvest_date }}^FS
^XZ
Pattern: Uses Twig-style variables for template rendering
See: BudTags TemplateService and LabelMakerService for integration
^XA
^FO50,50^GB400,300,3^FS // Box: width=400, height=300, thickness=3
^FO100,100^A0N,30,30^FDBoxed Text^FS
^FO50,400^GC100,3^FS // Circle: diameter=100, thickness=3
^XZ
See: volume-1/08-commands-graphics.md for all graphic commands
Template System:
TemplateService)data-zpl-* attributes)ZplApi service)Key Files:
app/Services/Api/ZplApi.php - ZPL generation serviceresources/js/Components/LabelDesigner/CanvasLabelDesigner.tsx - Visual designerresources/js/Components/TemplateEditor/VisualZplMapper.tsx - ZPL annotation toolresources/js/utils/ZplGenerator.ts - ZPL generation utilitiesresources/js/utils/HtmlProcessor.ts - HTML to ZPL conversionOutput Modes:
Coordinate System:
See: CLAUDE.md section "ZPL Integration & Visual Mapper" for complete architecture
Field Origin (^FO): Sets the starting position for field data
^FO100,50 // X=100 dots, Y=50 dots from top-left
Label Home (^LH): Sets the reference point for all field origins
^LH30,30 // All ^FO coordinates now relative to (30,30)
See: volume-1/12-commands-labels-media.md for label positioning
Font Command (^A): Selects font for subsequent text
^A0N,30,30 // Font 0, Normal orientation, Height=30, Width=30
^A0R,50,50 // Font 0, Rotated 90°, Height=50, Width=50
Font Types:
^A0 - Scalable font (recommended for flexibility)^A through ^A9 - Bitmap fonts^A@ - Custom downloaded fontsSee: volume-1/03-commands-fonts.md for all font commands
1D Barcodes: Linear barcodes (Code 39, Code 128, UPC, etc.)
^BCN,100,Y,N,N // Code 128, height=100, print interpretation line
^FD12345^FS // Barcode data
2D Barcodes: Matrix barcodes (QR Code, Data Matrix, etc.)
^BQN,2,4 // QR Code, model 2, magnification 4
^FDQA,Data^FS // QR data with error correction
See: volume-1/04a-04e-commands-barcodes-*.md for complete barcode reference
Graphic Primitives:
^GB - Box (rectangle)^GC - Circle^GD - Diagonal line^GE - Ellipse^GF - Graphic Field (custom graphics)Images:
~DG (Download Graphic)^XG (Recall Graphic)See: volume-1/08-commands-graphics.md and volume-1/10-commands-images.md
Stored Formats: Save label templates on printer for variable data
^DFR:FORMAT.ZPL^FS // Define stored format
^XA
^FO50,50^A0N,30,30^FN1^FS // ^FN1 = variable field 1
^XZ
^XF // End of format definition
// Call format with variable data
^XA
^XFR:FORMAT.ZPL^FS
^FN1^FDVariable Text^FS
^XZ
Serialization: Auto-increment fields for sequential labels
^SN123,1,Y // Start at 123, increment by 1, with leading zeros
See: volume-2/03a-advanced-stored-formats.md for complete details
RFID Commands: Write and encode RFID tags during printing
^RS8 // RFID Setup
^RFW,H^FD4E6F74654461746163^FS // Write hex data to RFID tag
See: volume-1/15-commands-rfid.md for RFID programming
volume-2/01-zpl-basics.md - Learn ZPL fundamentalsvolume-1/02-basic-exercises.md - 5 hands-on exercisesvolume-2/02-programming-exercises.md - 6 progressive exercisesvolume-2/03a-advanced-stored-formats.md - Variable data and serializationvolume-2/03b-advanced-control-commands.md - Advanced control techniquesvolume-2/04-fonts-barcodes.md - Font matrices and barcode implementationvolume-2/03c-advanced-graphics-networking.md - Graphics and networkingvolume-2/06-xml-super-host-status.md - XML status reportingvolume-2/05-printer-configuration.md - Printer tuning| Command | Purpose | File Reference | |---------|---------|----------------| | ^XA | Start label format | volume-2/01-zpl-basics.md | | ^XZ | End label format | volume-2/01-zpl-basics.md | | ^FO | Field Origin (position) | volume-1/07a-commands-fields-basic.md | | ^FD | Field Data (content) | volume-1/07a-commands-fields-basic.md | | ^FS | Field Separator | volume-1/07a-commands-fields-basic.md | | ^A0 | Scalable font | volume-1/03-commands-fonts.md | | ^BY | Barcode field default | volume-1/04a-commands-barcodes-basic.md | | ^BC | Code 128 barcode | volume-1/04c-commands-barcodes-advanced.md | | ^BQ | QR Code | volume-1/04d-commands-barcodes-2d.md | | ^GB | Graphic Box | volume-1/08-commands-graphics.md | | ^GC | Graphic Circle | volume-1/08-commands-graphics.md | | ^LL | Label Length | volume-1/12-commands-labels-media.md | | ^PQ | Print Quantity | volume-1/14-commands-print.md | | ^PR | Print Speed | volume-1/14-commands-print.md | | ^CF | Change Default Font | volume-1/03-commands-fonts.md | | ^FB | Field Block (text wrap) | volume-1/07b-commands-fields-advanced.md |
| Barcode Type | Command | File Reference | |--------------|---------|----------------| | Code 39 | ^B3 | volume-1/04a-commands-barcodes-basic.md | | Code 128 | ^BC | volume-1/04c-commands-barcodes-advanced.md | | UPC-A | ^BU | volume-1/04b-commands-barcodes-upc-ean.md | | UPC-E | ^B9 | volume-1/04b-commands-barcodes-upc-ean.md | | EAN-13 | ^BE | volume-1/04b-commands-barcodes-upc-ean.md | | QR Code | ^BQ | volume-1/04d-commands-barcodes-2d.md | | Data Matrix | ^BX | volume-1/04d-commands-barcodes-2d.md | | PDF417 | ^B7 | volume-1/04d-commands-barcodes-2d.md | | Aztec | ^BO | volume-1/04d-commands-barcodes-2d.md |
User asks: "How do I create a QR code in ZPL?"
You respond:
Use the ^BQ command for QR codes. Here's the syntax:
^BQa,b,c
- a: Orientation (N=normal, R=90°, I=180°, B=270°)
- b: Model (1 or 2, use 2 for enhanced)
- c: Magnification factor (1-10)
Example:
^XA
^FO100,100
^BQN,2,4
^FDQA,Your QR code data here^FS
^XZ
The ^FD data format is: ^FD<error_correction>,<data>^FS
Error correction levels: QA (high), QM (medium), QL (low), QH (highest)
For complete details and more examples, see docs/volume-1/04d-commands-barcodes-2d.md
User asks: "Show me how to create a cannabis label with strain name and THC percentage"
You respond:
Here's a ZPL template for a cannabis compliance label:
^XA
^FO50,50^GB400,350,3^FS // Border box
^FO100,80^A0N,35,35^FDCannabis Product^FS // Header
^FO100,130^A0N,28,28^FD{{ strain_name }}^FS // Strain (variable)
^FO100,180^A0N,25,25^FDTHC: {{ thc_percent }}%^FS // THC level
^FO100,220^A0N,25,25^FDCBD: {{ cbd_percent }}%^FS // CBD level
^FO100,270^BY2^BCN,80,Y,N,N^FD{{ package_tag }}^FS // Barcode
^XZ
This uses:
- ^GB for border box (volume-1/08-commands-graphics.md)
- ^A0 for scalable fonts (volume-1/03-commands-fonts.md)
- ^BC for Code 128 barcode (volume-1/04c-commands-barcodes-advanced.md)
- Twig-style variables for template integration with BudTags
The {{ }} variables get replaced with actual data in the BudTags TemplateService.
User asks: "My barcode isn't printing. How do I debug?"
You respond:
Common barcode issues and solutions:
1. Check barcode data format:
- Remove spaces and special characters
- Verify data matches barcode type requirements
- Code 128: Supports alphanumeric
- UPC-A: Must be exactly 11 or 12 digits
2. Verify barcode size:
^BY2 // Bar width multiplier (1-10)
^BCN,100 // Height in dots (minimum ~50 dots)
3. Check positioning:
^FO100,100 // Ensure barcode fits on label
4. Enable interpretation line for debugging:
^BCN,100,Y,N,N // Y = print human-readable text below barcode
5. Common errors:
- Data too long for barcode type
- Invalid characters for barcode type
- Barcode positioned off label edge
For detailed barcode troubleshooting, see:
- volume-1/04a-04e-commands-barcodes-*.md (specific barcode types)
- volume-2/04-fonts-barcodes.md (barcode implementation details)
- volume-2/09-error-detection-protocol.md (error handling)
User asks: "What's the difference between ^FO and ^FT?"
You respond:
^FO (Field Origin) vs ^FT (Field Typeset):
^FO (Field Origin):
- Sets bottom-left corner of field
- Traditional positioning method
- Used with ^FD for data
^FT (Field Typeset):
- Sets baseline of text (typography reference)
- More precise for font alignment
- Also used with ^FD for data
Example:
^FO50,100^A0N,30,30^FDText^FS // Bottom-left at (50,100)
^FT50,100^A0N,30,30^FDText^FS // Baseline at (50,100)
Most applications use ^FO. Use ^FT for precise typography alignment.
See docs/volume-1/07a-commands-fields-basic.md for complete details.
Labelary.com provides instant ZPL preview:
http://labelary.com/viewer.htmlPOST http://api.labelary.com/v1/printers/{dpi}/labels/{width}x{height}/{index}/BudTags Integration: VisualZplMapper component sends mock data ZPL to Labelary for preview
Get printer status and configuration:
~HS // Host Status (printer info)
~HI // Host Identification
^XA^HH^XZ // Configuration Status
See: volume-1/09-commands-host-status.md for all status commands
Enable error reporting:
~JN // Head Test (fatal)
^JZ // Reprint After Error
See: volume-2/09-error-detection-protocol.md for error handling
Help users successfully work with ZPL by:
You have complete knowledge of ZPL II Programming Language (volumes 1 & 2, 37 files, ~11,326 lines). Use it wisely!
A-C:
D-F:
G-L:
M-P:
R-Z:
Pro Tip: When users ask about specific ZPL commands, always reference the exact documentation file location so they can read more details if needed. Use real examples from the programming guide exercises when possible.
development
Use this skill to verify that code aligns with BudTags coding standards, architectural patterns, and conventions before or after implementation.
development
Use this skill when working with Unleashed Software inventory/order management API integration, syncing inventory, importing orders, managing stock adjustments, or handling customer/product data from Unleashed.
data-ai
TanStack Virtual patterns for virtualized lists, tables, and grids with high-performance rendering of large datasets
testing
Use when working with TanStack Table for data tables, datagrids, sorting, filtering, pagination, row selection, column customization, or virtualization. Load specific pattern files based on the feature needed.