Documentation

Everything you need to integrate KSeF Guard into your workflow.

Exit Codes

KSeF Guard uses these exit codes for automation:

Code	Meaning	CI Action
0	All files PASS (XSD valid + substantive compliant)	Pipeline passes
1	One or more files have XSD validation errors	Pipeline fails
2	One or more files have substantive compliance errors	Pipeline fails
10	Invalid arguments or missing required flags	Fix command line
11	Schema checksum verification failure	Reinstall or verify binary
12	File I/O error (not found, permission denied, size limit)	Check file paths and permissions
13	License/tier limit reached	Check license or upgrade
130	Interrupted by signal (SIGINT/SIGTERM)	Validation cancelled — re-run

When multiple error types occur, the highest-priority exit code is returned. Priority: Schema (11) > License (13) > IO (12) > XSD (1) > Substantive (2).

Recommended Configuration

Use --format summary for quick pass/fail in logs, --format json --output results.json for artifact archival.
Pro tier recommended for CI/CD (unlimited daily scans, YAML config support).
Activate your license before first use: ksef-guard license activate --key YOUR_KEY (machine-bound, stored locally).

CLI Usage

Common commands for validation:

# Validate a single file

ksef-guard validate invoice.xml

# Validate a directory of XML invoices

ksef-guard validate .\invoices\

# Machine-readable JSON output for artifact upload

ksef-guard validate --format json --output results.json .\invoices\

# Summary output for CI logs

ksef-guard validate --format summary .\invoices\

# CSV export

ksef-guard validate --format csv --output results.csv .\invoices\

# PDF report (Standard+)

ksef-guard validate --format pdf --output report.pdf .\invoices\

# With rule preset

ksef-guard validate --preset maximum .\invoices\

# With YAML config (Pro)

ksef-guard validate --config .ksef-guard.yml .\invoices\

# Render PDF from existing JSON results (Standard+)

ksef-guard render-pdf --input results.json --output report.pdf

# Activate license

ksef-guard license activate --key YOUR_KEY

# Check license status

ksef-guard license status --json

# Deactivate license (unbind machine)

ksef-guard license deactivate

# List all validation rules

ksef-guard --list-rules

# List rules as JSON (for tooling)

ksef-guard --list-rules --format json

# Erase all local data (license, history, config)

ksef-guard --erase-all-data --yes

Tier Feature Matrix

CLI features available at each tier:

Feature	Free	Standard+	Pro
Formats	text, summary	text, summary, csv, json, pdf	All formats
--output	No (stdout only)	Yes (--output)	Yes (--output)
Rule config	Default only	Enable/disable rules via CLI flags	YAML config + CLI flags
PDF	—	Standard branding	White-label (custom logo/header)
Daily quota	10 files/day	5,000 files/day	Unlimited

Configuration File

Create a .ksef-guard.yml file in your project root (requires Pro tier):

preset: recommended
rules:
  KSEF-BUS-030: warning
  KSEF-BUS-197: off

Presets

Built-in validation presets control which rules are active:

Preset	Active Rules	Warnings affect exit?
essential	GOV_MANDATED only	No
recommended	All active rules	No (default)
maximum	All active rules	Yes (exit 2)

GitHub Actions

Add this workflow to .github/workflows/ksef-validate.yml:

JSON output, --output, and license activation require Standard or Pro tier.

name: KSeF Validation
on:
  push:
    paths:
      - 'invoices/**/*.xml'
  pull_request:
    paths:
      - 'invoices/**/*.xml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download ksef-guard
        run: |
          curl -fsSL -o ksef-guard.tar.gz \
            "https://www.ksefguard.pl/downloads/ksef-guard-linux-amd64.tar.gz"
          tar -xzf ksef-guard.tar.gz
          chmod +x ksef-guard

      - name: Activate license (Standard/Pro)
        run: ./ksef-guard license activate --key ${{ secrets.KSEF_GUARD_LICENSE_KEY }}

      - name: Validate invoices
        run: |
          ./ksef-guard validate \
            --format json \
            --output results.json \
            ./invoices/

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: ksef-validation-results
          path: results.json
          retention-days: 30

GitLab CI

Add this job to your .gitlab-ci.yml:

JSON output, --output, and license activation require Standard or Pro tier.

ksef-validate:
  stage: validate
  image: ubuntu:latest
  before_script:
    - apt-get update -qq && apt-get install -y -qq curl
    - curl -fsSL -o ksef-guard.tar.gz
        "https://www.ksefguard.pl/downloads/ksef-guard-linux-amd64.tar.gz"
    - tar -xzf ksef-guard.tar.gz
    - chmod +x ksef-guard
    - ./ksef-guard license activate --key ${KSEF_GUARD_LICENSE_KEY}
  script:
    - ./ksef-guard validate
        --format json
        --output results.json
        ./invoices/
  artifacts:
    when: always
    paths:
      - results.json
    expire_in: 30 days
  rules:
    - changes:
        - invoices/**/*.xml

Tips

Run 'ksef-guard license activate --key YOUR_KEY' once per CI runner to bind the license to that machine.
Use --format json --output results.json and upload as a build artifact for traceability.
The --format summary output is compact and ideal for CI log readability.
Combine with --preset maximum or --warnings-as-errors for stricter compliance checks.
KSeF Guard validation runs offline — no network calls during validation. License and updates may connect.