CLI Tool

The zplflow command-line tool lets you manage conversions, async jobs, pipelines, and your account directly from the terminal — no code required.

Availability: Pre-built binaries for Windows, Linux, and macOS on amd64 and arm64 architectures. Published as a single static binary with zero system dependencies.

Installation

macOS / Linux (Homebrew)

The easiest way to install and keep the CLI updated on macOS and Linux:

brew install zplflow/tap/zplflow

Or tap the repository first:

brew tap zplflow/tap
brew install zplflow

Windows (Scoop)

If you use Scoop:

scoop bucket add zplflow https://github.com/zplflow/scoop-bucket
scoop install zplflow

Windows (winget)

Install via the official Windows Package Manager:

winget install zplflow.zplflow

Automated Script (macOS & Linux)

Install the latest static binary into /usr/local/bin (or ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/zplflow/zplflow-cli/main/scripts/install-cli.sh | bash

Linux Packages (.deb / .rpm)

Debian / Ubuntu:

# Download the .deb from GitHub Releases and install:
sudo dpkg -i zplflow_*_linux_amd64.deb

RHEL / CentOS / Fedora:

# Download the .rpm from GitHub Releases and install:
sudo rpm -i zplflow_*_linux_amd64.rpm

Download Pre-built Binary

Standalone archives (.tar.gz and .zip) and checksums are available on GitHub Releases:

Configuration

The CLI needs your API key to authenticate. Provide it via environment variable or flag:

Environment Variable (Recommended)

export ZPLFLOW_API_KEY="lb_YOUR_KEY"

This keeps the key out of your shell history.

Command-Line Flag

zplflow --api-key lb_YOUR_KEY account balance

Useful for one-off commands or scripting with a different key.

API URL

By default the CLI connects to https://api.zplflow.io. Override with ZPLFLOW_API_URL or --api-url:

export ZPLFLOW_API_URL="https://staging-api.zplflow.io"

Verbose mode

Pass --verbose to print diagnostic HTTP logs to stderr (method, full URL, status code, response time). Useful to self-debug before opening a support ticket.

zplflow --verbose convert zpl-to-pdf --file label.zpl --save out.pdf

Logs include request and response lines, but never the API key, request/response body, or presigned URL path.

Output Format

All commands support three output modes via --output:

Commands Reference

Contents: Account · Convert · Estimate · Jobs · Pipeline · Scopes · Version · Shell Completion

Account

zplflow account balance

Get your tenant’s token balance and reservations.

zplflow account balance

Tenant:        your-company
Balance:       10,000 tokens
Reserved:      3 tokens

# JSON for scripting
zplflow account balance --output json

{"tenant_id":"your-company","balance":10000,"reserved":3}

Estimate

zplflow estimate

Estimate the token cost of a conversion before running it. No payload analysis — purely parameter-based.

# PDF to ZPL estimate
zplflow estimate --operation pdf_to_zpl --dpi 203 --documents 10

# ZPL to PDF estimate
zplflow estimate --operation zpl_to_pdf --dpmm 8dpmm --documents 5

# EPL to ZPL estimate
zplflow estimate --operation epl_to_zpl --documents 10

# EPL to PDF estimate
zplflow estimate --operation epl_to_pdf --dpmm 8dpmm --documents 5

# ZPL to EPL estimate
zplflow estimate --operation zpl_to_epl --dpmm 8dpmm --documents 2

Convert

Synchronous conversions with inline payloads. No S3, no async — ideal for real-time label printing.

zplflow convert pdf-to-zpl

Convert a PDF file to ZPL text.

# From file, output to stdout
zplflow convert pdf-to-zpl --file shipping.pdf --dpi 203

# Save to file
zplflow convert pdf-to-zpl --file labels.pdf --dpi 300 --save output.zpl

# Read from stdin (pipe)
cat shipping.pdf | zplflow convert pdf-to-zpl --stdin > label.zpl

# With dimensions and fit
zplflow convert pdf-to-zpl --file large.pdf --dpi 203 --width 101.6 --height 152.4 --unit mm --fit contain

zplflow convert zpl-to-pdf

Convert a ZPL string to one or more PDF pages (one per input label).

The CLI automatically decodes the JSON envelope returned by the API and writes one PDF file per page, prefixed with a 1-based index.

# Single label → 1_<save>
zplflow convert zpl-to-pdf --file label.zpl --save output.pdf
# → output.pdf becomes 1_output.pdf

# Multi-label ZPL → 1_<save>, 2_<save>, 3_<save>, ...
echo -e '^XA^FO50,50^FD1^FS^XZ\n^XA^FO50,50^FD2^FS^XZ\n^XA^FO50,50^FD3^FS^XZ' \
  | zplflow convert zpl-to-pdf --stdin --save label.pdf
# → 1_label.pdf, 2_label.pdf, 3_label.pdf

# Custom density and dimensions
zplflow convert zpl-to-pdf --file label.zpl --save out.pdf --dpmm 12dpmm --width 101.6 --height 152.4

The numeric prefix is always applied — even with a single page — so the file count always equals the number of output pages. If --save includes a directory (--save /tmp/out/label.pdf), only the basename gets the prefix.

Note: PDF output is binary — --save is always required. The file path is never written to stdout.

zplflow convert epl-to-zpl

Convert an EPL2 label payload into ZPL II. Output is text/plain sent to stdout or written to a file via --save.

Metadata and token accounting are written to stderr, so stdout can be piped directly into downstream printers, spoolers, or file redirection.

# From file, output to stdout
zplflow convert epl-to-zpl --file label.epl

# Save to file
zplflow convert epl-to-zpl --file label.epl --save output.zpl

# Read from stdin (pipe)
cat label.epl | zplflow convert epl-to-zpl --stdin > label.zpl

zplflow convert epl-to-pdf

Convert an EPL2 label payload into one or more PDF pages (one per label).

The CLI decodes the JSON response returned by the API and writes one PDF file per page, prefixed with a 1-based index (e.g. 1_output.pdf).

# Single label → 1_<save>
zplflow convert epl-to-pdf --file label.epl --save output.pdf

# Custom density and dimensions
zplflow convert epl-to-pdf --file label.epl --save out.pdf --dpmm 8dpmm --width 101.6 --height 152.4

# Read from stdin
cat label.epl | zplflow convert epl-to-pdf --stdin --save label.pdf

Note: PDF output is binary — --save is always required. The file path is never written to stdout.

zplflow convert zpl-to-epl

Convert a ZPL II label into legacy EPL2 printer commands. The engine rasterizes the label canvas at 203 DPI (8 dpmm) and packages it into an EPL2 GW (Graphics Write) bit-packed stream. Output is sent to stdout or saved to --save.

# From file, output to stdout
zplflow convert zpl-to-epl --file label.zpl

# Save to file
zplflow convert zpl-to-epl --file label.zpl --save output.epl

# Read from stdin (pipe)
cat label.zpl | zplflow convert zpl-to-epl --stdin > label.epl

# Specify custom label dimensions in mm
zplflow convert zpl-to-epl --file label.zpl --save output.epl --dpmm 8dpmm --width 101.6 --height 152.4

zplflow convert dpl-to-zpl

Convert Datamax DPL text or binary streams into standard ZPL II format.

# From file, output to stdout
zplflow convert dpl-to-zpl --file legacy.dpl > label.zpl

# Save to file
zplflow convert dpl-to-zpl --file legacy.dpl --save output.zpl

# Read from stdin
cat legacy.dpl | zplflow convert dpl-to-zpl --stdin > label.zpl

zplflow convert dpl-to-pdf

Convert a Datamax DPL stream to one or more PDF pages via the internal high-speed ZPL pipeline.

# Single label → 1_<save>
zplflow convert dpl-to-pdf --file legacy.dpl --save output.pdf

# Custom density and dimensions
zplflow convert dpl-to-pdf --file legacy.dpl --save out.pdf --dpmm 12dpmm --width 101.6 --height 152.4

zplflow convert zpl-to-dpl

Convert a modern ZPL II label into legacy Datamax DPL commands with high-fidelity monochrome rasterization.

# Save to file
zplflow convert zpl-to-dpl --file label.zpl --save legacy.dpl

# Output to stdout
zplflow convert zpl-to-dpl --file label.zpl > legacy.dpl

zplflow convert ipl-to-zpl

Convert an Intermec Printer Language (IPL) file or stream to ZPL-II text.

# From file, output to stdout
zplflow convert ipl-to-zpl --file label.ipl

# Save to file
zplflow convert ipl-to-zpl --file label.ipl --save output.zpl

# Read from stdin (pipe)
cat label.ipl | zplflow convert ipl-to-zpl --stdin > label.zpl

zplflow convert ipl-to-pdf

Convert an IPL file or stream directly to PDF (via ZPL pipeline).

# Save to file (required)
zplflow convert ipl-to-pdf --file label.ipl --save output.pdf

# With custom density (300 DPI / 12dpmm)
zplflow convert ipl-to-pdf --file label.ipl --save output.pdf --dpmm 12dpmm

zplflow convert zpl-to-ipl

Convert a ZPL-II payload into an Intermec IPL graphic stream.

# From file, save to IPL file
zplflow convert zpl-to-ipl --file label.zpl --save output.ipl

# Pipe from stdin
echo '^XA^FO50,50^A0N,30,30^FDTest^FS^XZ' | zplflow convert zpl-to-ipl --stdin > output.ipl

zplflow convert tspl-to-zpl

Convert a TSPL / TSPL2 label file to standard ZPL II text.

# From file, output to stdout
zplflow convert tspl-to-zpl --file label.tspl

# Save ZPL to file
zplflow convert tspl-to-zpl --file label.tspl --save output.zpl

# Read from stdin (pipe)
cat label.tspl | zplflow convert tspl-to-zpl --stdin > output.zpl

zplflow convert tspl-to-pdf

Convert a TSPL / TSPL2 file directly to one or more PDF pages.

# Save to PDF (prefixed with 1_)
zplflow convert tspl-to-pdf --file label.tspl --save output.pdf

# Custom density and dimensions
zplflow convert tspl-to-pdf --file label.tspl --save out.pdf --dpmm 12dpmm --width 101.6 --height 152.4

zplflow convert zpl-to-tspl

Convert ZPL II text to TSPL / TSPL2 via high-fidelity monochrome rasterization (BITMAP).

# From file, output to stdout
zplflow convert zpl-to-tspl --file label.zpl

# Save to file
zplflow convert zpl-to-tspl --file label.zpl --save output.tspl --dpmm 8dpmm --width 101.6 --height 152.4

zplflow convert sbpl-to-zpl

Convert SATO SBPL commands to clean ZPL II text.

# From file, output to stdout
zplflow convert sbpl-to-zpl --file label.sbpl

# Save to file
zplflow convert sbpl-to-zpl --file label.sbpl --save output.zpl

# Read from stdin
cat label.sbpl | zplflow convert sbpl-to-zpl --stdin > label.zpl

zplflow convert sbpl-to-pdf

Transpiles SATO SBPL into ZPL and renders it directly into a high-fidelity PDF document.

# From file to output PDF
zplflow convert sbpl-to-pdf --file label.sbpl --save output.pdf
# → output.pdf becomes 1_output.pdf

# Custom density
zplflow convert sbpl-to-pdf --file label.sbpl --save out.pdf --dpmm 12dpmm

zplflow convert zpl-to-sbpl

High-fidelity monochrome rasterization of Zebra ZPL II into native SATO SBPL graphics hex commands.

# Convert ZPL file to SATO SBPL
zplflow convert zpl-to-sbpl --file label.zpl --save output.sbpl

# Custom density and dimensions in mm
zplflow convert zpl-to-sbpl --file label.zpl --save output.sbpl --dpmm 12dpmm --width 100 --height 150

Pipeline

zplflow pipeline apply <pipeline-id>

Apply a pre-defined pipeline transformation to ZPL documents.

# Single ZPL file
zplflow pipeline apply 550e8400-e29b-41d4-a716-446655440000 --zpl-file label.zpl

# Multiple documents via JSON file
zplflow pipeline apply 550e8400-... --json-file batch.json

# Save output to file
zplflow pipeline apply 550e8400-... --zpl-file label.zpl --save transformed.zpl

The pipeline ID is the first positional argument. Find your pipelines in the Admin UI.

Jobs

Async job management for bulk conversions and large files. The CLI handles the full lifecycle: create → upload → start → poll → download.

zplflow job create

Create and automatically start an async job.

# PDF to ZPL async
zplflow job create --operation pdf_to_zpl --file labels.pdf --dpi 203

# ZPL to PDF async
zplflow job create --operation zpl_to_pdf --file label.zpl

# Pipeline run
zplflow job create --operation pipeline_run --file labels.zpl --pipeline-id 550e8400-...

Job ID:         770e8400-e29b-41d4-a716-446655440000
Status:         queued
Tokens Reserved: 2

Monitor: zplflow job wait 770e8400-...

The create command uploads the input file via the presigned S3 URL and starts the job in a single step.

zplflow job list

List all async jobs for your tenant.

# Last 10 jobs
zplflow job list

# Filter by status, with table output
zplflow job list --status succeeded --limit 20

# Paginated
zplflow job list --status failed --cursor next-cursor-token

JOB ID                                STATUS      OPERATION
550e8400-e29b-41d4-a716-446655440000 succeeded   pdf_to_zpl
660e8400-e29b-41d4-a716-446655440000 failed      zpl_to_pdf

zplflow job get <job-id>

Get detailed status and results for a specific job.

zplflow job get 550e8400-e29b-41d4-a716-446655440000

Job ID:         550e8400-e29b-41d4-a716-446655440000
Operation:      pdf_to_zpl
Status:         succeeded
Tokens:         2 reserved / 2 committed
Results:        1 file(s)
  [0] 12,451 bytes  application/pdf
      URL: https://s3.amazonaws.com/... (expires 2026-01-15T11:00:00Z)
Meta:
  DPI:           203
  Budget KB:     32
  Degraded:      false
  Tile count:    1

zplflow job start <job-id>

Start a job that is in created state.

zplflow job start 550e8400-...

zplflow job cancel <job-id>

Cancel a queued or running job. Reserved tokens are rolled back.

zplflow job cancel 550e8400-...

zplflow job wait <job-id>

Poll a job until completion and automatically download the result. The recommended way to handle async jobs.

# Wait for result and save to file
zplflow job wait 550e8400-... --save result.pdf

# Custom timeout (default 5 minutes)
zplflow job wait 550e8400-... --save result.zpl --timeout 10m

# Without --save, prints text results to stdout (use for ZPL output)
zplflow job wait 550e8400-...

Waiting for job 550e8400-... [created]    1s
Waiting for job 550e8400-... [queued]     2s
Waiting for job 550e8400-... [running]    4s
Job succeeded! Saved 12,451 bytes to result.pdf

Polling uses exponential backoff starting at 1 second and capping at 8 seconds.

Scopes (catalog browsing)

The zplflow scopes subcommands inspect and print the scope catalog that the API uses to enforce per-key permissions. They hit the public GET /v1/scopes endpoint and therefore do not require ZPLFLOW_API_KEY — no bearer is sent and no token is consumed.

zplflow scopes list

Print every scope known to the running deployment, grouped by category.

# Human-readable grouped table (default)
zplflow scopes list

SCOPE ID                       GROUP       PUBLIC  ENDPOINTS
convert:pdf_to_zpl             convert     no      POST /v1/convert/pdf-to-zpl
convert:zpl_to_pdf             convert     no      POST /v1/convert/zpl-to-pdf
convert:epl_to_zpl             convert     no      POST /v1/convert/epl-to-zpl
convert:epl_to_pdf             convert     no      POST /v1/convert/epl-to-pdf
convert:zpl_to_epl             convert     no      POST /v1/convert/zpl-to-epl
convert:dpl_to_zpl             convert     no      POST /v1/convert/dpl-to-zpl
convert:dpl_to_pdf             convert     no      POST /v1/convert/dpl-to-pdf
convert:zpl_to_dpl             convert     no      POST /v1/convert/zpl-to-dpl
convert:ipl_to_zpl             convert     no      POST /v1/convert/ipl-to-zpl
convert:ipl_to_pdf             convert     no      POST /v1/convert/ipl-to-pdf
convert:zpl_to_ipl             convert     no      POST /v1/convert/zpl-to-ipl
convert:tspl_to_zpl            convert     no      POST /v1/convert/tspl-to-zpl
convert:tspl_to_pdf            convert     no      POST /v1/convert/tspl-to-pdf
convert:zpl_to_tspl            convert     no      POST /v1/convert/zpl-to-tspl
convert:sbpl_to_zpl            convert     no      POST /v1/convert/sbpl-to-zpl
convert:sbpl_to_pdf            convert     no      POST /v1/convert/sbpl-to-pdf
convert:zpl_to_sbpl            convert     no      POST /v1/convert/zpl-to-sbpl
convert:estimate               convert     no      POST /v1/estimate
jobs:create                    jobs        no      POST /v1/jobs
jobs:read                      jobs        no      GET /v1/jobs, GET /v1/jobs/{id}
jobs:write                     jobs        no      POST /v1/jobs/{id}/start, POST /v1/jobs/{id}/cancel
pipelines:read                 pipelines   no      GET /v1/pipelines, GET /v1/pipelines/{id}
pipelines:write                pipelines   no      POST /v1/pipelines, DELETE /v1/pipelines/{id}
pipelines:apply                pipelines   no      POST /v1/pipelines/preview, POST /v1/pipelines/{id}/apply
pipelines:prepackaged:read     pipelines   yes     GET /v1/pipelines/prepackaged*, POST .../adopt
account:read                   account     no      GET /v1/account/balance
account:export                 account     no      GET /v1/account/export
audit:read                     audit       no      GET /v1/audit/events
gdpr:delete:tenant             gdpr        no      DELETE /v1/tenants/{id}
gdpr:delete:user               gdpr        no      DELETE /v1/users/{email}
gdpr:breach_contact            gdpr        no      PUT /v1/tenants/{id}/breach-contact
apikeys:manage                 admin       no      GET/POST/DELETE /v1/apikeys

Machine-readable JSON

zplflow scopes list --output json | jq '.scopes | length'

{
  "version": "1",
  "description": "zplflow API+MCP scope catalog...",
  "scopes": [
    {
      "id": "convert:pdf_to_zpl",
      "group": "convert",
      "description": "Convert PDF documents to ZPL (sync, inline response).",
      "public": false,
      "tenant_feature_required": "",
      "http_endpoints": [
        { "method": "POST", "path": "/v1/convert/pdf-to-zpl" }
      ],
      "mcp_tools": ["convertPDFToZPL"]
    }
  ]
}

Emit a scope list ready to copy into POST /v1/apikeys

zplflow scopes list --embedded

["convert:pdf_to_zpl","convert:zpl_to_pdf","convert:epl_to_zpl","convert:epl_to_pdf","convert:zpl_to_epl","convert:dpl_to_zpl","convert:dpl_to_pdf","convert:zpl_to_dpl","jobs:create","jobs:read","jobs:write","pipelines:read","pipelines:apply"]

zplflow scopes show <scope_id>

Print full details for a single scope, including its MCP tools, tenant-feature prerequisite, and public flag.

zplflow scopes show pipelines:apply

ID:                       pipelines:apply
Group:                    pipelines
Public:                   no
Tenant feature required:  pipelines
HTTP endpoints:
  - POST /v1/pipelines/preview
  - POST /v1/pipelines/{id}/apply
MCP tools:
  - applyPipeline
Description:              Preview a pipeline or apply it to 1-5 ZPL documents.

zplflow scopes show pipelines:prepackaged:read --output json

{
  "id": "pipelines:prepackaged:read",
  "group": "pipelines",
  "description": "Browse and adopt prepackaged pipeline templates (always public).",
  "public": true,
  "tenant_feature_required": "",
  "http_endpoints": [
    { "method": "GET",  "path": "/v1/pipelines/prepackaged" },
    { "method": "GET",  "path": "/v1/pipelines/prepackaged/{id}" },
    { "method": "POST", "path": "/v1/pipelines/prepackaged/{id}/adopt" }
  ],
  "mcp_tools": []
}

Tip: The --output json form is identical to the live API response, so you can use it as a fixture in tests: zplflow scopes show apikeys:manage --output json > fixtures/scope_apikeys_manage.json.

Notes

• These commands never send Authorization. They are safe to run on developer machines without exposing credentials.
• The catalog returned by the CLI is fetched from the same GET /v1/scopes endpoint your application code uses, so a configured proxy (ZPLFLOW_API_URL) and custom scope builds are visible immediately.
• For deeper integration (issuing scoped keys, rotating scoped keys) see Self-Service API Keys.

Shell Completion

Generate tab-completion for your shell.

# Bash
zplflow completion bash > /etc/bash_completion.d/zplflow

# Zsh
zplflow completion zsh > "${fpath[1]}/_zplflow"

# Fish
zplflow completion fish > ~/.config/fish/completions/zplflow.fish

# PowerShell
zplflow completion powershell > zplflow.ps1

Version

zplflow version

zplflow version 1.2.3 (commit: abc1234, built: 2026-01-15T10:00:00Z)
go version go1.25.4 linux/amd64

# Short form — handy for scripting
zplflow version --short

1.2.3

Exit Codes

Use exit codes in scripts:

#!/bin/bash
if zplflow job wait "$JOB_ID" --save result.zpl --timeout 5m; then
    echo "Done: $(wc -c < result.zpl) bytes"
else
    code=$?
    echo "Failed with exit code $code"
fi

Idempotency

All POST commands automatically generate a unique Idempotency-Key (UUID v4) per request. This prevents duplicate operations on network retries.

The generated key is printed to stderr:

Idempotency Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890

To reuse a key for explicit retry control:

zplflow convert pdf-to-zpl --file labels.pdf --idempotency-key my-retry-001

Typical Workflows

Quick Sync Convert

export ZPLFLOW_API_KEY="lb_YOUR_KEY"

# PDF → ZPL (result to stdout)
zplflow convert pdf-to-zpl --file shipping.pdf --dpi 203 > label.zpl

# ZPL → PDF (result to file)
zplflow convert zpl-to-pdf --file label.zpl --save output.pdf

# EPL → ZPL (result to stdout)
zplflow convert epl-to-zpl --file legacy.epl > modern.zpl

# EPL → PDF (result to file)
zplflow convert epl-to-pdf --file legacy.epl --save label.pdf

# ZPL → EPL (result to file)
zplflow convert zpl-to-epl --file label.zpl --save legacy.epl

# DPL → ZPL (result to stdout)
zplflow convert dpl-to-zpl --file legacy.dpl > modern.zpl

# DPL → PDF (result to file)
zplflow convert dpl-to-pdf --file legacy.dpl --save label.pdf

# ZPL → DPL (result to file)
zplflow convert zpl-to-dpl --file label.zpl --save legacy.dpl

# TSPL → ZPL
zplflow convert tspl-to-zpl --file label.tspl --save label.zpl

# TSPL → PDF
zplflow convert tspl-to-pdf --file label.tspl --save output.pdf

# ZPL → TSPL (raster for TSC printers)
zplflow convert zpl-to-tspl --file label.zpl --save label.tspl

Async Batch Processing

# Step 1: Create and start job
JOB_ID=$(zplflow job create --operation pdf_to_zpl --file labels.pdf --dpi 203 --output json | jq -r '.job_id')
echo "Job: $JOB_ID"

# Step 2: Wait for completion
zplflow job wait "$JOB_ID" --save result.zpl

Pipeline in a CI/CD Pipeline

# Apply pipeline transformation
zplflow pipeline apply "$PIPELINE_ID" --zpl-file label.zpl --save transformed.zpl

# Then convert to PDF for preview
zplflow convert zpl-to-pdf --file transformed.zpl --save preview.pdf

Error Messages

The CLI translates API errors into human-readable messages:

Security

• The API key is never logged or printed in output
• Use the environment variable (ZPLFLOW_API_KEY) to avoid leaking keys in shell history
• Presigned S3 URLs are never logged
• Payload content (PDF/ZPL) is never logged
• Gzip compression is transparent: the CLI sends Accept-Encoding: gzip and compresses large request bodies automatically

Next Steps

• Authentication — Full auth reference and scope model
• Conversions — Sync API parameters and pricing
• Jobs API — Async workflow details
• Pipelines — ZPL transformation recipes
• Self-Service API Keys — programmatic key management
• Best Practices — Production integration guide