Komut Satırı (CLI)

npx labelixa ile CI hattında etiket doğrulama ve önizleme: glob, ZPL/EPL/TSPL/CPCL, --json, çıkış kodları; GitHub Actions, GitLab, Azure ve Bitbucket örnekleri.

labelixa npm paketi bir komut satırı aracı taşır. Etiket dosyalarını yazıcıya göndermeden önce hattın içinde doğrular ve önizlemesini üretir; API'nin ince bir kabuğudur, ikinci bir motor değildir.

Kurulum

Node.js 18+ yeterlidir. npx paketi her koşuda indirir; kalıcı kurulum için global yükleyin.

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

macOS'ta Homebrew ile de kurulur (tap Node.js'i bağımlılık olarak getirir):

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

Hızlı başlangıç

# 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 desenlerini (**, *, ?) CLI kendisi açar; tırnak içinde verilen desen Windows koşucularında da aynı çalışır.

Komutlar

Seçenekler

Diller

Dil dosya uzantısından seçilir; --lang bunu ezer. ZPL'de yoğunluk ve boyut parametreleri geçerlidir, öteki dillerde boyut kodun kendisinden okunur.

Çıkış kodları

--json çıktısı

Tek belge, dosya başına bir sonuç. diagnostics API'nin tanı kaydının aynısıdır (kod, önem, satır/sütun, mesaj); failed eşiği aşan dosya sayısı, apiFailed API hatasıyla düşen dosya sayısıdır.

{
 "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
}

Kimlik ve kota

Anahtar YALNIZ LABELIXA_API_KEY ortam değişkeninden okunur; argüman olarak kabul edilmez (ps ve kabuk geçmişi argümanı sızdırır). Hedef adres LABELIXA_API_URL ile değişir (on-prem kurulum).

Anahtarsız kullanım anonim hız sınırına tabidir; 429 yanıtı sunucunun Retry-After süresi kadar bekleyip en fazla iki kez, görünür biçimde yeniden denenir. Her istek X-Client: cli/<sürüm> başlığı taşır; kişi değil araç sayılır.

GitHub Action

GitHub'da en kısa yol Marketplace'teki Labelixa ZPL Lint eylemidir: CLI'ı sarmalar, bulguları kural sayfası bağlantısıyla iş özetine yazar, pull request'te önce/sonra önizleme verir ve PNG'leri artefakt olarak yükler.

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

Girdiler: files, fail-on, language, dpmm/width/height, render, previews, artifact, api-key, api-url (on-prem). Anahtar isteğe bağlıdır; verilmezse anonim hız sınırı uygulanır. Tam liste eylemin README'sinde.

CI örnekleri

Dört platformda aynı komut. Anahtar her platformun gizli değişken mekanizmasında durur, hattın dosyasında değil.

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 kancası

Etiket dosyaları daha commit edilmeden denetlensin isterseniz paket bir pre-commit kancası taşır. .pre-commit-config.yaml dosyanıza ekleyin:

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]

Kanca sahnelenmiş .zpl, .prn, .epl, .tspl, .cpcl dosyalarında labelixa validate koşturur (dil uzantıdan). Sır gerekmez: ortamda LABELIXA_API_KEY yoksa anonim hız sınırı uygulanır. Kanca bilerek seri çalışır — API'nin hız sınırı paylaşımlıdır, paralel örnekler yalnız 429 kazanır.

SDK

Aynı paket Node.js SDK'sıdır: Client sınıfı, renderPng/validate (dört dil), renderPdf, toEpl. Kullanım örnekleri Kod Örnekleri sayfasında.