zplCloud CLI
api.zplcloud.com. Wendet Druckerprofile an, sendet Roh-ZPL und Druckaufträge anderer Druckersprachen (TCP 9100 / USB), provisioniert Weblink-Zertifikate, betreibt den ausgehenden Proxy-Agenten und den Ordner-Watch-Druck.
Funktionen
- profiles apply - führt ein gespeichertes Druckerprofil (SGD-/ZPL-Befehlsfolge mit Variablen) über TCP 9100 oder USB auf einem Drucker aus.
- send - sendet Roh-ZPL aus Argument oder Datei und Druckaufträge anderer Druckersprachen (TSPL, EPL2, DPL, SBPL, CPCL, ESC/POS, Brother-Raster, PCL, Easy Plug, TPCL, JScript) byte-genau - fertig oder mit
--languageaus ZPL umgewandelt. - weblink setup - erzeugt die Weblink-Zertifikate serverseitig, lädt sie hoch, setzt
weblink.ip.conn2.location, startet den Drucker neu. - proxy - Remote-Agent: eine ausgehende SignalR-Verbindung zu
api.zplcloud.com; Jobs aus dem Tab „Remote Printers“ werden an LAN-Drucker (TCP 9100) oder USB-Drucker weitergeleitet. Keine eingehenden Ports. - font - Schriften und Dateien im Druckerspeicher verwalten: auflisten, hochladen (
~DY), löschen und den Plattform-FontZPLCLOUD.TTFinstallieren - direkt am Drucker oder über einen Remote-Drucker. - remote-printers list - die Remote-Drucker des Kontos mit ID, Ziel und Agent-Status auflisten.
- USB - unter Windows zwei Bordmittel-Kanäle (WinUSB und die USBPRINT-Schnittstelle von
usbprint.sys, beide bidirektional und ohne Spooler), unter Linux/macOS libusb-Druckerklasse oder virtueller COM-Port. - Watch-Ordner - der Agent druckt jede neue
.zpl-/.prn-Datei aus konfigurierten Ordnern, fertige Aufträge wie.tsplbyte-genau und wandelt ZPL auf Wunsch für andere Drucker um (siehe unten).
Installation
Der Installer erkennt Betriebssystem und Architektur und lädt das Binary von https://zplcloud.com/downloads/.
macOS / Linux / Raspberry Pi
Ziele: osx-x64, osx-arm64, linux-x64, linux-arm64 (64-Bit Pi OS), linux-arm (32-Bit Raspberry Pi).
Windows (PowerShell, ohne Admin)
Installiert nach %LOCALAPPDATA%\zplcloud\zplcloud.exe und ergänzt das Verzeichnis im Benutzer-PATH (neue Terminals). Ziele: win-x64, win-arm64.
Docker
Agent als Container für Raspberry Pi, Synology und jeden Docker-Host: CLI als Docker-Container.
API-Key
Wird in der Plattform unter API erstellt. Übergabe per Umgebungsvariable oder --api-key:
Befehle
zplcloud profiles list
Listet die Druckerprofile des Kontos (ID, Name, Zielkonfiguration).
zplcloud profiles apply
Führt alle Befehle eines Profils nacheinander auf einem Drucker aus; die Antwort jedes Befehls wird live ausgegeben.
| Parameter | Bedeutung |
|---|---|
| <id-or-name> | Profil-ID (Zahl) oder Profilname (in Anführungszeichen). |
| --target <ip|hostname> | TCP-Ziel des Druckers; Standardport 9100. |
| --port <n> | TCP-Port (Standard 9100). |
| --usb | Über einen virtuellen USB-COM-Port statt TCP senden. |
| --serial-port <name> | Expliziter serieller Port (COM3, /dev/cu.usbmodem1101, …); leer = Zebra-Drucker automatisch erkennen. |
| --var name=value | Befehlsvariable setzen (wiederholbar). |
| --vars-file file.json | JSON-Objekt mit Variablenwerten. |
| --non-interactive | Bei fehlenden Variablen abbrechen statt nachzufragen. |
| --timeout <ms> | Verbindungs-/Lese-Timeout (Standard 5000). |
zplcloud cookbook list
Listet die ZPL-Cookbook-Rezepte (Befehls-Snippets mit Variablen).
zplcloud send
Sendet Roh-ZPL. Ein fehlender Zeilenabschluss wird ergänzt (\r\n), weil der SGD-Parser des Zebra-Druckers ein Kommando ohne CRLF nicht verarbeitet. Ausnahme sind Druckaufträge anderer Druckersprachen: sie gehen byte-genau raus, ohne Zeilenabschluss (siehe Andere Druckersprachen).
Die Antwort des Druckers wird automatisch gelesen, wenn das Kommando eine liefert: SGD-Abfragen (! U1 …), JSON-Config ({}{"allconfig":null}), Host-Status (~HS, ~HI, ~HQ…) und ZPL-Host-Befehle (^HW Verzeichnis, ^HH Konfiguration). Mit --read lässt sich das erzwingen. Bleibt ein dösender Drucker stumm, wird er mit ~HS geweckt und die Abfrage einmal wiederholt - nur Abfragen, ein setvar wird nie doppelt gesendet. Dieselbe Regel gilt für den Proxy-Agenten.
| Parameter | Bedeutung |
|---|---|
| --target <ip|hostname> | TCP-Ziel (Pflicht, außer bei --usb). |
| --port <n> | TCP-Port (Standard 9100). |
| --zpl "<zpl>" | ZPL inline (entweder --zpl oder --file). Für SGD-Befehle mit Anführungszeichen --file verwenden, um Shell-Escaping zu vermeiden. |
| --file <path> | ZPL- oder SGD-Datei senden (als UTF-8-Text gelesen, fehlendes CRLF wird ergänzt). Dateien mit der Endung einer Druckersprache (.tspl, .bin …) gehen byte-genau raus. Firmware: zplcloud firmware. |
| --raw | --file unabhängig von der Endung byte-genau senden: kein Text-Lesen, kein Zeilenabschluss, keine Antwort. |
| --language <id> | ZPL über die API in eine andere Druckersprache umwandeln und den Auftrag byte-genau senden (API-Key nötig, siehe unten). |
| --remote-printer <id|name> | Statt direkt über die Cloud an den Agenten im LAN des Druckers: ZPL über /v1/remote-printers/{id}/send, Druckaufträge über /v1/remote-printers/{id}/raw. API-Key nötig. |
| --usb / --serial-port | Über USB statt TCP senden (siehe profiles apply). |
Andere Druckersprachen (TSPL, DPL, Brother …)
Die Werkzeuge ZPL → Druckersprache und POST /v1/tools/zpl-to-… machen aus einem ZPL-Etikett einen fertigen Auftrag für TSC-, Honeywell/Datamax-, SATO-, Brother-, Toshiba-, cab-, Avery-Dennison/Novexx-, Epson- oder HP-Drucker. Ein solcher Auftrag enthält binäre Bilddaten und muss unverändert beim Drucker ankommen. Die CLI schafft das auf drei Wegen:
| Weg | Befehl | Braucht |
|---|---|---|
| Fertiger Auftrag, direkt | zplcloud send --target 10.0.0.7 --file label.tsplzplcloud send --usb --file label.bin | nichts - keinen API-Key |
| ZPL umwandeln, dann senden | zplcloud send --target 10.0.0.7 --file label.zpl --language tspl --dpi 300 --compress | API-Key (zählt Renders wie das Werkzeug) |
| Über einen Remote-Drucker | zplcloud send --remote-printer 4 --file label.dplzplcloud send --remote-printer Lager --file label.zpl --language brother --model td-4-300 | API-Key; Agent ab v1.2.22 für TCP-Drucker, ab v1.2.26 für USB-Drucker |
Dateien mit den Endungen .tspl .epl .dpl .sbpl .cpcl .escpos .bin .pcl .ezp .tpcl .jscript - so benennen die Werkzeuge ihre Downloads - gehen automatisch byte-genau raus; --raw macht dasselbe für jede andere Datei. Bis v1.2.25 las die CLI jede Datei als Text und hängte CRLF an, was binäre Aufträge zerstört - CLI und Agent auf v1.2.26 aktualisieren.
| Option (mit --language) | Bedeutung |
|---|---|
| --language <id> | tspl, epl2, dpl, sbpl, cpcl, escpos, brother, pcl, easyplug, tpcl oder jscript. |
| --dpi <n> | Auflösung des Zieldruckers (erlaubte Werte je Sprache wie im Werkzeug). Brother: ergibt sich aus --model. |
| --width-mm / --height-mm | Etikettengröße; Standard aus ^PW/^LL, sonst 75 × 50 mm. |
| --compress | Komprimiertes Bildformat, wo die Sprache eins hat (PCX, TIFF PackBits, TOPIX, #YIR). |
| --hex | SBPL und CPCL: Bilddaten als Hex-Text. |
| --cut false | ESC/POS und Brother: nach dem Auftrag nicht schneiden. |
| --paper a4|letter | PCL: Papierformat. |
| --model <id> / --media continuous|diecut | Brother: Modellfamilie (z. B. ql-820, td-4-300, pt-p900) und Medientyp. |
| --save <pfad> | Den umgewandelten Auftrag zusätzlich als Datei behalten. |
zplcloud font
Verwaltet Schriften und Dateien im Druckerspeicher - dieselbe Mechanik wie der Dialog „Fonts/Files“ in der Plattform: auflisten über ! U1 getvar "file.dir", löschen über ^ID, hochladen als ~DY{drive}:{name},B,T,{size},, mit den rohen Bytes. Nach dem Upload wird per file.dir geprüft, ob die Datei wirklich im Flash liegt (der Drucker braucht dafür einige Sekunden).
| Parameter | Bedeutung |
|---|---|
| list | install | upload | delete | Auflisten, Plattform-Font installieren, beliebige TTF hochladen, Datei löschen. |
| --target <ip> / --usb | Direkter Druckerzugriff (TCP 9100 bzw. USB). |
| --remote-printer <id|name> | Über die Cloud an den Agenten im LAN des Druckers (/v1/remote-printers/{id}/file). Braucht einen API-Key und einen Agenten ab v1.2.22. |
| --drive <E|R> | Ziel-Laufwerk: E: Flash (Standard, überlebt den Neustart), R: RAM. |
| --file <ttf> | Lokale Datei. Bei install optional - sonst kommt der Font aus der Cloud. |
| --name <NAME> | Name im Druckerspeicher (Standard: Dateiname bzw. ZPLCLOUD.TTF). |
| --replace | Vorhandene gleichnamige Datei vorher löschen (install macht das immer). |
ZPLCLOUD.TTF ist rund 10 MB - auf E: muss entsprechend Platz frei sein; die vorhandene Datei wird vorher gelöscht. Der Upload über einen Remote-Drucker läuft nur über TCP 9100, nicht über USB.
zplcloud remote-printers list
Listet die Remote-Drucker des Kontos mit ID, Ziel, zugeordnetem Agenten und dessen Status. Die IDs sind das, was font --remote-printer und send --remote-printer erwarten.
zplcloud weblink setup
Erzeugt die drei NRD-Zertifikatsdateien serverseitig (API-Key erforderlich), lädt sie per ~DYE hoch, setzt weblink.ip.conn2.location und startet den Drucker neu. Liest die Seriennummer und registriert Besitzer + API-Key im Backend (auch für Ersatzgeräte).
| Parameter | Bedeutung |
|---|---|
| --printer <hostname> | Druckername (Zertifikats-Scope / NRD-Ablage). |
| --endpoint <url> | Weblink-URL: https://weblink.zplcloud.com (Prod) oder https://weblink.test.zplcloud.com (Test). |
| --target / --port | TCP-Ziel + Port (Standard 9100). |
| --api-key / --api-base | API-Key (Pflicht). Test-Stage: Key + api-base des Test-Backends. |
Ohne CLI: Weblink-Zertifikats-Deployment (servergenerierter PowerShell-/bash-Einzeiler).
zplcloud proxy
Startet den Remote-Agenten. Ausgehende SignalR-Verbindung zu api.zplcloud.com; Jobs aus dem Tab „Remote Printers“ werden an Drucker im lokalen LAN (TCP 9100) oder USB weitergeleitet.
| Parameter | Bedeutung |
|---|---|
| --agent <name> | Anzeigename im Tab Remote Printers (Pflicht). |
| --timeout <ms> | Verbindungs-/Lese-Timeout (Standard 5000). |
| --verbose | --debug | SignalR-Negotiation-/Transport-/Handshake-Trace mit Zeitstempeln. |
| --log | Gesamte Konsolenausgabe nach zplcloud-<yyyy-MM-dd>.log schreiben. |
| --log-dir <dir> | Log-Verzeichnis (Standard: aktuelles Verzeichnis). |
| --service-install | Als Systemdienst installieren (systemd / launchd / geplante Aufgabe). Benötigt --agent + API-Key. |
| --service-uninstall | Dienst entfernen (kein API-Key nötig). |
zplcloud proxy --service-install
Installiert den Agenten als Dienst, der beim Booten/Login startet und sich automatisch neu verbindet. API-Key, Agentname, API-Base und Timeout werden in die Dienstdefinition geschrieben.
| System | Mechanismus | Start |
|---|---|---|
| Linux / Raspberry Pi | systemd-Unit zplcloud-agent.service (Restart=always, RestartSec=5) | beim Booten (sudo nötig, wird automatisch erkannt) |
| macOS | launchd LaunchAgent ~/Library/LaunchAgents/com.zplcloud.agent.plist (KeepAlive=true) | beim Login, ohne Admin |
| Windows | geplante Aufgabe zplcloud-agent (schtasks ONLOGON, /RL LIMITED) | beim Login, ohne Admin |
Optional: --timeout <ms>, --log-dir <dir> (Standard: Linux /var/log/zplcloud, macOS /tmp, Windows %LOCALAPPDATA%\zplcloud\logs). In Docker ersetzt restart: unless-stopped den Dienst (siehe CLI als Docker-Container).
zplcloud usb list
Listet serielle Ports und die Zebra-USB-Kanäle. Unter Windows gibt es zwei Bordmittel-Wege, beide bidirektional und ohne Spooler oder Fremdtreiber:
| Kanal | Wann er greift |
|---|---|
| WinUSB | Der Drucker bietet WinUSB nativ an (ZD421: usb.device.mode = composite) und Windows hat die Schnittstelle registriert. |
| USBPRINT | Fallback über die Geräteschnittstelle von usbprint.sys, direkt per CreateFile geöffnet. Nötig, wenn Windows für den Drucker keine WinUSB-Schnittstelle registriert - das kommt vor, obwohl winusb.sys gebunden ist. |
Das CLI versucht erst WinUSB, dann USBPRINT, dann den virtuellen COM-Port. Unter Linux/macOS läuft es über die libusb-Druckerklasse.
zplcloud version / help
zplcloud version / --version zeigt die Version, zplcloud help / --help die vollständige Hilfe.
Datenquellen am Agenten
Der Agent kann zusätzlich zu Druckern auch Datenbanken anbinden. Die Abfrage läuft dann in Ihrem Netz, der Connection-String bleibt lokal und über die Leitung gehen nur die Ergebniszeilen. Jede Engine hat ihren eigenen Namensraum; alle drei Wege (Option, Umgebungsvariable, Datei) sind gleichwertig. Details, Abfrage-Regeln und der agentenlose Cloud-Weg stehen unter Konnektoren.
| Engine | Option | Umgebungsvariable | Datei |
|---|---|---|---|
| SQL Server | --sql NAME=… | ZPLCLOUD_SQL_<NAME>_CONNECTION | sqlservers.json |
| MongoDB | --mongo NAME=… | ZPLCLOUD_MONGO_<NAME>_CONNECTION | mongoservers.json |
| PostgreSQL | --postgres NAME=… | ZPLCLOUD_PG_<NAME>_CONNECTION | pgservers.json |
| MySQL | --mysql NAME=… | ZPLCLOUD_MYSQL_<NAME>_CONNECTION | mysqlservers.json |
| MariaDB | --mariadb NAME=… | ZPLCLOUD_MARIADB_<NAME>_CONNECTION | mariadbservers.json |
| Kafka | --kafka NAME=… | ZPLCLOUD_KAFKA_<NAME>_CONNECTION | kafkabrokers.json |
Globale Optionen
| Option | Bedeutung |
|---|---|
| --api-key <key> | API-Key. |
| --api-base <url> | Backend-Basis-URL (Standard https://api.zplcloud.com). |
| --log / --log-dir | Logging (siehe proxy). |
Umgebungsvariablen
| Variable | Bedeutung |
|---|---|
| ZPLCLOUD_API_KEY | API-Key (Alternative zu --api-key). |
| ZPLCLOUD_API_BASE | Basis-URL (Alternative zu --api-base). |
| ZPLCLOUD_AGENT | Agentname (wie --agent; in Docker genutzt). |
| ZPLCLOUD_TIMEOUT | Verbindungs-/Lese-Timeout in ms. |
Ausgabe von --help
Ordner-Watch-Druck
Der Agent überwacht konfigurierte Ordner und sendet jede neue .zpl-/.prn-Datei an einen LAN-Drucker (TCP 9100) oder USB. Regeln: älteste Datei zuerst, eine Datei nach der anderen je Ordner; gedruckt wird erst, wenn der letzte Schreibzugriff älter als stabilitySeconds ist; *.part/*.tmp werden übersprungen; nach Erfolg wird die Datei gelöscht (deleteAfterOk) oder behalten; Fehlerdateien wandern nach failedSubDir.
Konfiguration je Agent in der Online-Agent-Config (GET/PUT /api/remote-printers/agents/{agent}/config); Änderungen werden live gepusht (UpdateAgentConfig), kein Neustart.
Ordner-Ziele erscheinen in Druckerlisten als wf:<agent>:<folder> („Agent / 📁 Ordner“): die Plattform legt das ZPL als Datei in den Ordner, der Agent druckt es. Endpunkte: GET /api/remote-printers/agents/{agent}/folders, POST …/folders/send; Public API GET /v1/agents/folders, POST /v1/print/folder mit { "agent", "folder", "zpl" }.
Watch-Ordner für andere Druckersprachen
Ab Agent v1.2.26 bedient ein Watch-Ordner auch Drucker, die kein ZPL sprechen - auf zwei Arten:
- Fertige Aufträge - Dateien mit den Endungen
.tspl.epl.dpl.sbpl.cpcl.escpos.bin.pcl.ezp.tpcl.jscriptgehen byte-genau raus. Die Endung inpatternaufnehmen, z. B."*.zpl;*.tspl". - ZPL umwandeln - mit
convertmacht der Agent aus jeder ZPL-Datei vor dem Druck die Sprache des Druckers (POST /v1/tools/zpl-to-…mit dem API-Key des Agenten, zählt Renders wie das Werkzeug). ERP oder Versandsoftware schreiben weiter ZPL; ein TSC-, Honeywell- oder Brother-Drucker bekommt seine eigene Sprache. Optionen wie im Werkzeug:language,dpi,widthMm,heightMm,compress,hex,cut,paper,model,media.
Auch die Public API legt Druckaufträge in so einen Ordner: POST /v1/print/folder mit { "agent", "folder", "zpl", "language": "tspl", "dpi": 300 } (die Cloud wandelt um) oder { "agent", "folder", "base64", "fileName": "label.tspl" } (fertiger Auftrag). Die Datei behält die Endung des Auftrags, das pattern des Ordners muss sie also enthalten - sonst antwortet der Agent mit einem Fehler, statt eine Datei abzulegen, die nie gedruckt würde.