Kommandozeile (CLI)

Etiketten in der CI mit npx labelixa prüfen und rendern: Globs, ZPL/EPL/TSPL/CPCL, --json, Exit-Codes; Beispiele für GitHub Actions, GitLab, Azure, Bitbucket.

Das npm-Paket labelixa enthält ein Kommandozeilen-Werkzeug. Es prüft Etikettdateien und rendert Vorschauen in der Pipeline, bevor etwas den Drucker erreicht; es ist eine dünne Hülle über der API, keine zweite Engine.

Installation

Node.js 18+ genügt. npx lädt das Paket bei jedem Lauf; für eine dauerhafte Einrichtung global installieren.

npx labelixa --version
# or install once:
npm install -g labelixa

Unter macOS geht es auch mit Homebrew (der Tap zieht Node.js als Abhängigkeit nach):

brew tap labelixa/tap
brew trust labelixa/tap   # Homebrew 7+: third-party taps are trusted once
brew install labelixa

Schnellstart

# lint every label; exit code 1 on error findings
npx labelixa validate "labels/**/*.zpl"

# warnings also fail the build; JSON report for the job log
npx labelixa validate "labels/**/*.zpl" --fail-on warning --json > report.json

# one PNG per label as a build artifact
npx labelixa render "labels/**/*.zpl" --dpmm 8 --width 4 --height 6 --out-dir previews/

# a single label straight to a file
npx labelixa render shipping.zpl --format pdf --out shipping.pdf

Glob-Muster (**, *, ?) löst die CLI selbst auf; ein Muster in Anführungszeichen funktioniert auf Windows-Runnern genauso.

Befehle

Optionen

Sprachen

Die Sprache folgt der Dateiendung; --lang überschreibt sie. Dichte und Größe gelten für ZPL; die anderen Sprachen lesen die Größe aus dem Code.

Exit-Codes

--json-Ausgabe

Ein Dokument, ein Ergebnis je Datei. diagnostics ist der Diagnose-Datensatz der API unverändert (Code, Schwere, Zeile/Spalte, Meldung); failed zählt Dateien über der Schwelle, apiFailed Dateien mit API-Fehler.

{
 "version": "0.4.0",
 "command": "validate",
 "failOn": "error",
 "results": [
  {
   "file": "labels/ship.zpl",
   "language": "zpl",
   "ok": false,
   "summary": {"error": 1, "warning": 1, "info": 0},
   "diagnostics": [
    {"code": "ZPL1001", "severity": "error", "line": 1, "col": 4,
     "mesaj": "Unknown command: ^QQ",
     "url": "https://labelixa.com/zpl/rules/ZPL1001"}
   ]
  }
 ],
 "failed": 1,
 "apiFailed": 0
}

Authentifizierung und Kontingent

Der Schlüssel wird NUR aus der Umgebungsvariable LABELIXA_API_KEY gelesen und nicht als Argument akzeptiert (ps und Shell-Verlauf geben Argumente preis). LABELIXA_API_URL ändert das Ziel (On-Premise).

Ohne Schlüssel gilt das anonyme Ratenlimit; eine 429-Antwort wird höchstens zweimal sichtbar nach dem Retry-After des Servers wiederholt. Jede Anfrage trägt X-Client: cli/<Version>; gezählt wird das Werkzeug, keine Person.

GitHub Action

Auf GitHub ist der kürzeste Weg die Labelixa ZPL Lint Action im Marketplace: sie kapselt die CLI, schreibt Befunde mit Regel-Links in die Job-Zusammenfassung, liefert bei Pull Requests Vorher/Nachher-Vorschauen und lädt die PNGs als Artefakt hoch.

name: labels
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: Labelixa/labelixa-action@v1
        with:
          files: "labels/**/*.zpl"
          fail-on: warning
          api-key: ${{ secrets.LABELIXA_API_KEY }}   # optional; anonymous quota without it

Eingaben: files, fail-on, language, dpmm/width/height, render, previews, artifact, api-key, api-url (On-Premise). Der Schlüssel ist optional; ohne ihn gilt das anonyme Ratenlimit. Die vollständige Liste steht in der README der Action.

CI-Beispiele

Derselbe Befehl auf vier Plattformen. Der Schlüssel liegt im Geheimnis-Speicher der jeweiligen Plattform, nie in der Pipeline-Datei.

GitHub Actions — .github/workflows/labels.yml

name: labels
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx labelixa validate "labels/**/*.zpl" --fail-on warning
        env:
          LABELIXA_API_KEY: ${{ secrets.LABELIXA_API_KEY }}
      - run: npx labelixa render "labels/**/*.zpl" --out-dir previews/
      - uses: actions/upload-artifact@v4
        with:
          name: label-previews
          path: previews/

GitLab CI — .gitlab-ci.yml

validate-labels:
  image: node:20
  script:
    - npx labelixa validate "labels/**/*.zpl" --fail-on warning
    - npx labelixa render "labels/**/*.zpl" --out-dir previews/
  artifacts:
    paths: [previews/]
  # LABELIXA_API_KEY: Settings > CI/CD > Variables (masked)

Azure Pipelines — azure-pipelines.yml

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
  - script: npx labelixa validate "labels/**/*.zpl" --fail-on warning
    env:
      LABELIXA_API_KEY: $(LABELIXA_API_KEY)
  - script: npx labelixa render "labels/**/*.zpl" --out-dir $(Build.ArtifactStagingDirectory)/previews
  - publish: $(Build.ArtifactStagingDirectory)/previews
    artifact: label-previews

Bitbucket Pipelines — bitbucket-pipelines.yml

pipelines:
  default:
    - step:
        image: node:20
        script:
          - npx labelixa validate "labels/**/*.zpl" --fail-on warning
          - npx labelixa render "labels/**/*.zpl" --out-dir previews/
        artifacts:
          - previews/**
        # LABELIXA_API_KEY: Repository settings > Repository variables (secured)

pre-commit-Hook

Damit Etikettdateien schon vor dem Commit geprüft werden, liefert das Paket einen pre-commit-Hook mit. In .pre-commit-config.yaml eintragen:

repos:
  - repo: https://github.com/Labelixa/labelixa-sdk
    rev: v0.3.3
    hooks:
      - id: labelixa-validate
        # optional: fail on warnings too
        # args: [--fail-on, warning]

Der Hook führt labelixa validate für gestagte Dateien mit den Endungen .zpl, .prn, .epl, .tspl, .cpcl aus (Sprache nach Endung). Kein Geheimnis nötig: ohne LABELIXA_API_KEY in der Umgebung gilt das anonyme Ratenlimit. Der Hook läuft bewusst seriell — das Ratenlimit der API ist geteilt, parallele Instanzen würden nur 429 ernten.

SDK

Dasselbe Paket ist das Node.js-SDK: die Klasse Client, renderPng/validate (vier Sprachen), renderPdf, toEpl. Beispiele stehen auf der Seite Codebeispiele.