zplCloud CLI
What is the zplCloud CLI?
The zplcloud CLI is a small, self-contained command-line tool
(a single binary) that connects to api.zplcloud.com with an API key.
With it you can provision Zebra printers directly from the terminal -
without the web UI:
- Apply printer profiles - the printer profiles saved in zplCloud are transferred to a printer (TCP 9100 or USB).
- Send raw ZPL - send a label straight to the printer from the command line.
- Set up Weblink - store the Weblink certificates on the printer.
- Remote proxy agent - an outbound SignalR connection to zplCloud; print jobs from the "Remote Printers" tab are forwarded to the printers in the local LAN over TCP 9100. No inbound ports, no firewall changes.
- USB printers - send ZPL via virtual COM ports (e.g.
COM3,/dev/ttyACM0,/dev/cu.usbmodem1101).
Installation
The installer detects the operating system and architecture automatically and downloads the matching binary from https://zplcloud.com/downloads/.
macOS / Linux / Raspberry Pi (one line)
Supported platforms: osx-x64, osx-arm64 (Apple Silicon), linux-x64, linux-arm64 (64-bit Pi OS), linux-arm (32-bit Raspberry Pi).
Windows (PowerShell, no admin)
Installs to %LOCALAPPDATA%\zplcloud\zplcloud.exe and adds the directory to the user PATH (new terminals). Supports win-x64 and win-arm64.
Alternatively: Docker (agent as a container)
See CLI as a Docker container - for Raspberry Pi, Synology and any Docker host, without managing the CLI file path.
Prerequisites
An API key from the zplCloud API tab. Pass it via an environment variable or
--api-key:
Commands (reference)
zplcloud profiles list
Lists all printer profiles of your account (ID, name, printer target configuration).
zplcloud profiles apply
Applies a saved profile to a specific printer - all commands of the profile are executed in sequence (with a live response per command).
| Parameter | Meaning |
|---|---|
| <id-or-name> | Profile ID (number) or profile name (in quotes). |
| --target <ip|hostname> | TCP target of the printer (IP or hostname), default port 9100. |
| --port <n> | TCP port (default: 9100). |
| --usb | Send over a USB virtual COM port instead of TCP. |
| --serial-port <name> | Explicit serial port (COM3, /dev/cu.usbmodem1101, …); empty = auto-detection of the Zebra printer. |
| --var name=value | Set a command variable (repeatable). |
| --vars-file file.json | JSON object with variable values. |
| --non-interactive | Fail instead of prompting interactively for missing variables. |
| --timeout <ms> | Connection/read timeout (default: 5000). |
zplcloud cookbook list
Lists the available ZPL cookbook recipes (articles/snippets).
zplcloud send
Sends raw ZPL to a printer - directly from the command line or from a file.
| Parameter | Meaning |
|---|---|
| --target <ip|hostname> | TCP target (required). |
| --port <n> | TCP port (default: 9100). |
| --zpl "<zpl>" | ZPL code directly (either --zpl or --file). |
| --file <path> | Send a ZPL file (either --zpl or --file). |
| --usb / --serial-port | Optional: send over USB instead of TCP (see profiles apply). |
zplcloud weblink setup
Sets up the Weblink connection on a printer (sets weblink.ip.conn2.location to the Weblink endpoint).
| Parameter | Meaning |
|---|---|
| --printer <hostname> | Printer name (NRD storage/scope). |
| --endpoint <url> | Weblink URL (e.g. https://weblink.zplcloud.com). |
| --target / --port | TCP target + port (default 9100) to the printer. |
zplcloud proxy
Starts the remote agent (TeamViewer style): outbound SignalR connection to api.zplcloud.com. Print jobs from the "Remote Printers" tab are forwarded to Zebra printers in the local LAN over TCP 9100.
| Parameter | Meaning |
|---|---|
| --agent <name> | Display name in the "Remote Printers" tab (required). |
| --timeout <ms> | Connect/read timeout (default: 5000). |
| --verbose | --debug | SignalR negotiation/transport/handshake trace (with timestamps) for connection diagnosis. |
| --log | Writes the complete console output to zplcloud-<yyyy-MM-dd>.log. |
| --log-dir <dir> | Log directory (default: current directory). |
| --service-install | Install the proxy as a system service (systemd / launchd / Windows scheduled task) - survives reboots, reconnects automatically. Needs --agent + API key. |
| --service-uninstall | Remove an installed service (no API key needed). |
zplcloud proxy --service-install (system service)
So the remote agent survives reboots and reconnects to
api.zplcloud.com automatically after every start, it can be installed
as a system service with a single parameter. API key, agent name, API base and
timeout are written into the service:
Depending on the operating system, the matching mechanism is used automatically:
| System | Mechanism | Start |
|---|---|---|
| Linux / Raspberry Pi | systemd unit zplcloud-agent.service (Restart=always, RestartSec=5) | at boot (needs sudo, detected automatically) |
| macOS | launchd LaunchAgent ~/Library/LaunchAgents/com.zplcloud.agent.plist (KeepAlive=true) | at login, no admin needed |
| Windows | scheduled task zplcloud-agent (schtasks ONLOGON, /RL LIMITED) | at login, no admin needed |
Check status / uninstall:
Optional parameters: --timeout <ms>, --log-dir <dir> (default:
Linux /var/log/zplcloud, macOS /tmp, Windows %LOCALAPPDATA%\zplcloud\logs).
Logs (Linux): journalctl -u zplcloud-agent -f or the file in --log-dir.
Docker: In the container approach this is already done -
restart: unless-stopped in docker-compose.agent.yml restarts the agent
automatically (see CLI as a Docker container).
zplcloud usb list
Lists serial/USB ports and Zebra USB printers (libusb) - useful for --serial-port.
zplcloud version / help
zplcloud version or --version shows the version; zplcloud help or --help shows the full help.
Global options
| Option | Meaning |
|---|---|
| --api-key <key> | API key from the zplCloud API tab. |
| --api-base <url> | Backend base URL (default: https://api.zplcloud.com). |
| --log / --log-dir | Logging (see proxy). |
Environment variables
| Variable | Meaning |
|---|---|
| ZPLCLOUD_API_KEY | API key (alternative to --api-key). |
| ZPLCLOUD_API_BASE | Base URL (alternative to --api-base). |
| ZPLCLOUD_AGENT | Agent name (same as --agent, useful in a Docker container). |
| ZPLCLOUD_TIMEOUT | Connect/read timeout in ms. |