zplcloud.com/docs

Was ist die zplCloud CLI?

Die zplcloud-CLI ist ein kleines, selbstenthaltenes Kommandozeilen-Werkzeug (ein einzelnes Binary), das sich per API-Key mit api.zplcloud.com verbindet. Damit kannst du Zebra-Drucker direkt aus dem Terminal provisionieren - ohne die Web-Oberfläche:

Drucker-Profile anwenden - die in zplCloud gespeicherten Printer-Profile werden auf einen Drucker übertragen (TCP 9100 oder USB).
Rohes ZPL senden - ein Label per Kommandozeile direkt auf den Drucker schicken.
Weblink einrichten - die Weblink-Zertifikate auf dem Drucker hinterlegen.
Remote-Proxy-Agent - eine ausgehende SignalR-Verbindung zu zplCloud; Druckaufträge aus dem „Remote Printers“-Tab werden im lokalen LAN über TCP 9100 an die Drucker weitergegeben. Keine eingehenden Ports, keine Firewall-Änderung.
USB-Drucker - ZPL über virtuelle COM-Ports (z. B. COM3, /dev/ttyACM0, /dev/cu.usbmodem1101) senden.

Installation

Der Installer erkennt Betriebssystem und Architektur automatisch und lädt das passende Binary von https://zplcloud.com/downloads/.

macOS / Linux / Raspberry Pi (ein Zeile)

curl -fsSL https://zplcloud.com/install-cli.sh | sh
# oder:  wget -qO- https://zplcloud.com/install-cli.sh | sh
zplcloud --version

Unterstützte Plattformen: osx-x64, osx-arm64 (Apple Silicon), linux-x64, linux-arm64 (64-bit Pi OS), linux-arm (32-bit Raspberry Pi).

Windows (PowerShell, ohne Admin)

irm https://zplcloud.com/install-cli-pshell | iex
zplcloud --version

Installiert nach %LOCALAPPDATA%\zplcloud\zplcloud.exe und trägt das Verzeichnis in den Benutzer-PATH ein (neue Terminals). Unterstützt win-x64 und win-arm64.

Alternativ: Docker (Agent als Container)

Siehe CLI als Docker-Container - für Raspberry Pi, Synology und jeden Docker-Host, ohne den CLI-Dateipfad verwalten zu müssen.

Voraussetzungen

Ein API-Key aus dem zplCloud-API-Tab. Übergib ihn per Umgebungsvariable oder --api-key:

# Umgebungsvariable (empfohlen):
export ZPLCLOUD_API_KEY=sk_zplcloud_xxxx
# Windows PowerShell:
$env:ZPLCLOUD_API_KEY='sk_zplcloud_xxxx'
# oder pro Befehl:
zplcloud profiles list --api-key sk_zplcloud_xxxx

Kommandos (Referenz)

zplcloud profiles list

Listet alle Drucker-Profile deines Kontos auf (ID, Name, Drucker-Zielkonfiguration).

zplcloud profiles list

zplcloud profiles apply

Wendet ein gespeichertes Profil auf einen konkreten Drucker an - alle Kommandos des Profils werden der Reihe nach ausgeführt (mit Live-Antwort je Kommando).

zplcloud profiles apply 42 --target 10.0.0.5
zplcloud profiles apply "Factory Reset" --target printer01.local --vars-file vars.json

Parameter	Bedeutung
<id-or-name>	Profil-ID (Zahl) oder Profilname (mit Anführungszeichen).
--target <ip\|hostname>	TCP-Ziel des Druckers (IP oder Hostname), Standard-Port 9100.
--port <n>	TCP-Port (Standard: 9100).
--usb	Statt TCP über einen USB-virtuellen-COM-Port senden.
--serial-port <name>	Expliziter Seriell-Port (COM3, /dev/cu.usbmodem1101, …); leer = Auto-Erkennung des Zebra-Druckers.
--var name=value	Kommando-Variable setzen (wiederholbar).
--vars-file file.json	JSON-Objekt mit Variablenwerten.
--non-interactive	Fehlschlagen statt interaktiv nach fehlenden Variablen zu fragen.
--timeout <ms>	Verbindungs-/Lese-Timeout (Standard: 5000).

zplcloud cookbook list

Listet die verfügbaren ZPL-Kochbuch-Rezepte (Fachartikel/Snippets) auf.

zplcloud cookbook list

zplcloud send

Sendet rohes ZPL an einen Drucker - direkt aus der Kommandozeile oder aus einer Datei.

zplcloud send --target 10.0.0.5 --zpl "^XA^FO50,50^ADN,36,20^FDHello^FS^XZ"
zplcloud send --target 10.0.0.5 --file label.zpl

Parameter	Bedeutung
--target <ip\|hostname>	TCP-Ziel (Pflicht).
--port <n>	TCP-Port (Standard: 9100).
--zpl "<zpl>"	ZPL-Code direkt (entweder --zpl oder --file).
--file <path>	ZPL-Datei senden (entweder --zpl oder --file).
--usb / --serial-port	Optional: über USB statt TCP senden (siehe profiles apply).

zplcloud weblink setup

Richtet die Weblink-Verbindung auf einem Drucker ein (setzt weblink.ip.conn2.location auf den Weblink-Endpoint).

zplcloud weblink setup --printer printer01 --endpoint https://weblink.zplcloud.com --target 10.0.0.5

Parameter	Bedeutung
--printer <hostname>	Druckername (NRD-Ablage/Scope).
--endpoint <url>	Weblink-URL (z. B. https://weblink.zplcloud.com).
--target / --port	TCP-Ziel + Port (Standard 9100) zum Drucker.

zplcloud proxy

Startet den Remote-Agenten (TeamViewer-Stil): ausgehende SignalR-Verbindung zu api.zplcloud.com. Druckaufträge aus dem „Remote Printers“-Tab werden an Zebra-Drucker im lokalen LAN über TCP 9100 weitergegeben.

zplcloud proxy --agent "Warehouse Berlin"
zplcloud proxy --agent "PI" --verbose --log --log-dir ./logs

Parameter	Bedeutung
--agent <name>	Anzeigename im „Remote Printers“-Tab (Pflicht).
--timeout <ms>	Connect-/Read-Timeout (Standard: 5000).
--verbose \| --debug	SignalR-Negotiation-/Transport-/Handshake-Trace (mit Zeitstempeln) zur Verbindungsdiagnose.
--log	Schreibt die komplette Konsolenausgabe in `zplcloud-<yyyy-MM-dd>.log`.
--log-dir <dir>	Log-Verzeichnis (Standard: aktuelles Verzeichnis).
--service-install	Proxy als Systemdienst installieren (systemd / launchd / Windows-Scheduled-Task) - überlebt Neustarts, verbindet sich automatisch neu. Braucht `--agent` + API-Key.
--service-uninstall	Installierten Dienst entfernen (kein API-Key nötig).

zplcloud proxy --service-install (Systemdienst)

Damit der Remote-Agent Neustarts überlebt und sich nach jedem Start automatisch wieder mit api.zplcloud.com verbindet, kann er mit einem einzigen Parameter als Systemdienst installiert werden. API-Key, Agenten-Name, API-Base und Timeout werden fest in den Dienst geschrieben:

zplcloud proxy --agent "Warehouse Berlin" --service-install --api-key sk_zplcloud_xxxx

Je nach Betriebssystem wird dabei automatisch der passende Mechanismus verwendet:

System	Mechanismus	Start
Linux / Raspberry Pi	systemd-Unit `zplcloud-agent.service` (`Restart=always`, `RestartSec=5`)	beim Boot (braucht sudo, wird automatisch erkannt)
macOS	launchd LaunchAgent `~/Library/LaunchAgents/com.zplcloud.agent.plist` (`KeepAlive=true`)	beim Login, kein Admin nötig
Windows	geplante Aufgabe `zplcloud-agent` (schtasks ONLOGON, `/RL LIMITED`)	beim Login, kein Admin nötig

Status prüfen / deinstallieren:

# Status
Linux/Pi : systemctl status zplcloud-agent       |  journalctl -u zplcloud-agent -f
macOS    : launchctl list | grep zplcloud
Windows  : schtasks /Query /TN zplcloud-agent

# Deinstallieren (ohne API-Key)
zplcloud proxy --service-uninstall

Optionale Parameter: --timeout <ms>, --log-dir <dir> (Standard: Linux /var/log/zplcloud, macOS /tmp, Windows %LOCALAPPDATA%\zplcloud\logs). Logs (Linux): journalctl -u zplcloud-agent -f oder die Datei im --log-dir.

Docker: Beim Container-Ansatz ist das bereits erledigt - restart: unless-stopped in docker-compose.agent.yml startet den Agenten automatisch neu (siehe CLI als Docker-Container).

zplcloud usb list

Listet Seriell-/USB-Ports und Zebra-USB-Drucker (libusb) auf - nützlich für --serial-port.

zplcloud usb list

zplcloud version / help

zplcloud version bzw. --version zeigt die Version; zplcloud help bzw. --help zeigt die vollständige Hilfe.

Globale Optionen

Option	Bedeutung
--api-key <key>	API-Key aus dem zplCloud-API-Tab.
--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	Agenten-Name (entspricht --agent, nützlich im Docker-Container).
ZPLCLOUD_TIMEOUT	Connect-/Read-Timeout in ms.

Vollständige --help-Ausgabe

zplcloud v1.2.15
zplCloud.com CLI - provision Zebra printers from zplCloud.com printer profiles.

USAGE:
  zplcloud profiles list
  zplcloud profiles apply <id-or-name> --target <ip|hostname> [--port 9100] [--var name=value ...] [--vars-file file.json]
  zplcloud cookbook list
  zplcloud send --target <ip|hostname> [--port 9100] (--zpl "<zpl>" | --file <path>)
  zplcloud weblink setup --printer <hostname> --endpoint <url> --target <ip|hostname> [--port 9100]
  zplcloud proxy --agent <name> [--timeout <ms>] [--verbose|--debug] [--log [--log-dir <dir>]]
  zplcloud usb list
  zplcloud version
  zplcloud help

TRANSPORT (apply/send/weblink):
  --target <ip|hostname>   TCP target (default port 9100)
  --port <n>               TCP port (default: 9100)
  --usb                    Use a USB virtual COM port instead of TCP
  --serial-port <name>     Explicit serial port (COM3, /dev/cu.usbmodem1101, ...)
  --bluetooth              (not supported yet - reserved for future RFCOMM transport)
  --timeout <ms>           Connect/read timeout (default: 5000)

PROXY (indirect realtime sending, no inbound firewall ports):
  zplcloud proxy --agent "Warehouse Berlin" [--verbose|--debug]
  Connects OUTBOUND to api.zplcloud.com and forwards print commands from the
  'Remote Printers' tab to Zebra printers in the local LAN over TCP 9100.
  --verbose/--debug prints SignalR negotiation/transport/handshake trace
  (with timestamps) to diagnose connection problems.

VARIABLES (profiles apply):
  --var name=value         Set a command variable (repeatable)
  --vars-file file.json    JSON object with variable values
  --non-interactive        Fail instead of prompting for missing required variables

API:
  --api-key <key>          API key from the zplCloud API tab
  --api-base <url>         api.zplcloud.com base URL (default: https://api.zplcloud.com)
  Environment: ZPLCLOUD_API_KEY, ZPLCLOUD_API_BASE

LOGGING:
  --log                    Write all console output to zplcloud-<yyyy-MM-dd>.log
  --log-dir <dir>          Log directory (default: current directory)

VERSION:
  --version                Print the version and exit
  zplcloud version

Beispiele

# Profile ansehen
zplcloud profiles list

# Profil 42 auf Drucker 10.0.0.5 anwenden
zplcloud profiles apply 42 --target 10.0.0.5

# Variablen setzen
zplcloud profiles apply "GTIN-Label" --target 10.0.0.5 --var gtin=4006381333930 --var charge=LOT-42
zplcloud profiles apply 42 --target 10.0.0.5 --vars-file vars.json

# ZPL direkt senden
zplcloud send --target 10.0.0.5 --zpl "^XA^FO50,50^A0N,50^FDHello^FS^XZ"

# Remote-Agent starten
zplcloud proxy --agent "Warehouse Berlin"

# USB-Drucker ansprechen
zplcloud usb list
zplcloud profiles apply 42 --usb --serial-port /dev/ttyACM0