zugcmd – the command-line tool for ZUGFeRD and XRechnung

Code samples

Command line

Published

2026-10-12

zugcmd.exe is the command-line tool of the Aloaha ZUGFeRD SDK. With it you create and process electronic invoices according to EN 16931 (ZUGFeRD, Factur-X, XRechnung) without writing code: from batch files, scheduled tasks, scripts, VBA/Access or directly from SQL Server. Every call returns an exit code, so zugcmd is easy to integrate into existing workflows.

What zugcmd can do

• Create ZUGFeRD from CSV: seller, buyer, line items, totals and allowances/charges come from simple CSV files; the result is the ZUGFeRD/XRechnung XML and, if required, the finished ZUGFeRD PDF/A-3.
• Embed XML into a PDF: an existing ZUGFeRD/XRechnung XML is embedded into your invoice PDF (PDF/A-3).
• PDF from XML via a Word template: without an existing PDF, zugcmd creates the invoice from a DOCX template.
• Export e-invoices to CSV: a ZUGFeRD/XRechnung XML or a ZUGFeRD PDF is split back into the CSV files – e.g. for importing into your accounting system.
• DOCX visualisation: a readable Word document is created from the XML.
• ASCII/DAT files: invoice data in SAP/inconso format ("SATZART") is converted directly to ZUGFeRD.
• Signing (new in 11.0.0.3): sign existing PDFs or the ZUGFeRD invoice just created – with a local certificate or via the CodeB remote signature (PAdES) of the CodeB EUID Wallet, even in a single call.

Internally, zugcmd uses the same functions as your own code, such as ImportCSV, MergeXMLIntoPDF, CreateDocFromXML and SignPDFRemote.

Download and setup

zugcmd is available as zugcmd.zip on the download page – with sample CSV files and a detailed readme.txt. Some functions of the included library must be registered in the system once: run zugcmd once with administrator rights (e.g. with a first invoice) or install one of the installers from the download page. For the licensed functions, pass your licence key with -l; you can get a free trial licence from info@aloaha.com.

Requirement: zugcmd version 11 and later requires .NET Framework 4.7.2 (already included in Windows 10 from version 1803 and in Windows 11). Versions 10 and older run with the .NET Framework 3.5 runtime.

Integration into your own application: how to build the CSV files, start zugcmd from Delphi, VB6 or another language and evaluate the exit code is shown in Creating e-invoices via CSV and zugcmd from your own application – with tested sample files.

Parameters

Parameters start with - or / (e.g. -x or /x). Put paths containing spaces in quotation marks.

General

Input and output files

CSV files (import and export)

Signing (from version 11.0.0.3)

Remote signing runs via the CodeB Remote Signature Service – part of the CodeB EUID Wallet software, which is now also used for ZUGFeRD.

With -i alone (and optionally -o) zugcmd signs an existing PDF. Combined with ZUGFeRD creation – embedding XML, CSV, Word template or ASCII – the generated output PDF is signed at the very end, so the embedded XML remains unchanged. If -remoteurl is set, remote signing takes precedence over -cert.

If signing fails, no unsigned PDF is left under the target name: zugcmd renames it to <name>.pdf.unsigned (exit code 60 or 1). If a signature was requested but no output PDF was created, zugcmd ends with exit code 62. This way, a follow-up process that only looks for the PDF file can never pass on an unsigned invoice by mistake.

The structure of the CSV files is described in the article Importing CSV files into a ZUGFeRD-compliant XRechnung (German).

Examples

1. Create ZUGFeRD from CSV (XML and PDF)

zugcmd.exe -x "OutputXML.xml" -o "OutputPDF.pdf" -i "InputPDF.pdf" ^
  -b "Buyer.csv" -s "Seller.csv" -p "Items.csv" -t "Totals.csv" ^
  -z "allowances.csv" -y "," -l <licence-key>

Short form with a base directory – all files there carry their default names:

zugcmd.exe -d "C:\Daten" -y "," -l <licence-key>

2. Embed an existing XML into a PDF

zugcmd.exe -x "C:\Daten\rechnung.xml" -i "C:\Daten\rechnung.pdf" ^
  -o "C:\Daten\zugferd.pdf" -l <licence-key>

3. Export ZUGFeRD or XRechnung to CSV

zugcmd.exe -d "C:\Daten" -r "xrechnung.xml" -b "Buyer.csv" -s "Seller.csv" ^
  -p "Items.csv" -t "Totals.csv" -z "allowances.csv" -y "," -l <licence-key>

Instead of the XML, -r also accepts a ZUGFeRD PDF directly. More on this: Converting ZUGFeRD invoices to CSV (German).

4. ASCII/DAT file (SAP/inconso) to ZUGFeRD

zugcmd.exe -a "rechnung.DAT" -i "rechnung.pdf" -o "zugferd.pdf" -f true ^
  -l <licence-key>

5. DOCX visualisation

Add -v "C:\Daten\visualisierung.docx" to any of the calls; zugcmd then writes a readable Word version of the invoice.

6. PDF from XML via a Word template

zugcmd.exe -x "C:\Daten\rechnung.xml" -w "C:\Daten\Vorlage.docx" ^
  -o "C:\Daten\rechnung.pdf" -l <licence-key>

The placeholders of the template are explained in the article Word template and placeholders (German).

7. From CSV via the Word template to PDF (two steps)

CSV import and Word template cannot be combined in one call. First create the XML from the CSV files, then the PDF from the template:

zugcmd.exe -d "C:\Daten" -x "zugferd.xml" -b "Buyer.csv" -s "Seller.csv" ^
  -p "Items.csv" -t "Totals.csv" -z "allowances.csv" -y "," -l <licence-key>

zugcmd.exe -x "C:\Daten\zugferd.xml" -w "C:\Daten\Vorlage.docx" ^
  -o "C:\Daten\zugferd.pdf" -l <licence-key>

Important for the second step: use full paths and do not point -d at the CSV folder – otherwise the call is treated as a CSV import again and the template is ignored. The output file must not exist yet in this step. In the first step a notice about the missing input PDF (exit code 57/58) may appear; the XML is written anyway.

8. Sign an existing PDF via remote signing

set ZUGCMD_REMOTE_PASSWORD=YOUR-PASSWORD
zugcmd.exe -remoteurl "https://YOUR-CODEB-SERVER" -remoteuser "benutzer@firma.de" ^
  -level B-LTA -i "C:\Daten\rechnung_zugferd.pdf" -o "C:\Daten\rechnung_signiert.pdf" ^
  -reason "Invoice approval" -l <licence-key>

9. Create a ZUGFeRD PDF and sign it in one call

zugcmd.exe -x "C:\Daten\rechnung.xml" -i "C:\Daten\basis.pdf" -o "C:\Daten\rechnung_zugferd.pdf" ^
  -remoteurl "https://YOUR-CODEB-SERVER" -remoteuser "benutzer@firma.de" -l <licence-key>

With -cert "<thumbprint>" instead of the -remote… parameters, the output PDF is signed with your local certificate.

Return values (exit codes)

0 means success, any other value an error. Batch files, VBA or SQL Server can therefore evaluate the result directly.

An example batch file:

zugcmd.exe -d "C:\Daten" -y ";" -silent -l <licence-key>
if errorlevel 1 echo ZUGFeRD creation failed, ExitCode %errorlevel%

More command-line tools

• Direct conversion of doc/docx to PDF/A (German)
• Command-line printing of Office doc/docx documents (German)
• Converting ZUGFeRD XML to Word (DOCX) (German)
• All articles on the command-line tools (German)

Prefer a user interface? The Aloaha ZUGFeRD GUI creates, edits and signs ZUGFeRD files at the click of a mouse. Started without arguments, zugcmd shows a short overview of all parameters.