This page documents the command-line interface for the gobl.cii tool, which provides a simple way to convert documents between GOBL JSON and CII XML formats. For programmatic usage of the conversion library in Go applications, see Go API Usage. For details on the supported e-invoicing standards and their configurations, see Supported E-Invoicing Standards.
The CLI tool is installed using Go's standard toolchain:
This installs the gobl.cii binary to your $GOPATH/bin directory. Ensure this directory is in your system PATH to run the command from anywhere.
Prerequisites:
Sources: README.md109-113
Sources: cmd/gobl.cii/convert.go22-32 cmd/gobl.cii/convert.go34-115
The primary command is convert, which handles bidirectional conversion between GOBL and CII formats.
Arguments:
| Argument | Required | Description |
|---|---|---|
<infile> | Yes | Input file path (JSON or XML) |
[outfile] | No | Output file path (defaults to stdout) |
Flags:
| Flag | Short | Default | Description |
|---|---|---|---|
--context | en16931 | E-invoicing standard to use for XML output |
The command implementation is defined in the convertOpts struct cmd/gobl.cii/convert.go13-16 and registered through the cmd() method cmd/gobl.cii/convert.go22-32
Sources: cmd/gobl.cii/convert.go22-32 README.md116-125
The --context flag specifies which e-invoicing standard to use when converting from GOBL to CII XML. This flag is ignored for CII-to-GOBL conversions, as the standard is detected from the input XML.
| Context Flag | Context Constant | Standard Name |
|---|---|---|
en16931 | cii.ContextEN16931V2017 | European EN 16931 base standard |
peppol | cii.ContextPeppolV3 | Peppol BIS Billing 3.0 |
xrechnung | cii.ContextXRechnungV3 | German XRechnung 3.0 |
facturx | cii.ContextFacturXV1 | French/German Factur-X |
zugferd | cii.ContextZUGFeRDV2 | German ZUGFeRD 2.x |
choruspro | cii.ContextChorusProV1 | French Chorus Pro |
The context resolution logic is implemented in cmd/gobl.cii/convert.go40-56 Additional context values exist in the library (such as Peppol France variants) but are not exposed through the CLI as of this version.
Sources: cmd/gobl.cii/convert.go29 cmd/gobl.cii/convert.go40-56 README.md59-69
The CLI automatically detects the input format and performs the appropriate conversion:
The detection is implemented using Go's json.Valid() function at cmd/gobl.cii/convert.go76 which checks if the input bytes form valid JSON. This approach is simple but effective, as CII documents are always XML and GOBL envelopes are always JSON.
Important: The --context flag only affects GOBL-to-CII conversion. When converting from CII to GOBL, the context is automatically detected from the XML's GuidelineSpecifiedDocumentContextParameter element, so the flag is ignored.
Sources: cmd/gobl.cii/convert.go76-108
The CLI accepts input from either a file path or stdin:
Input file opening is handled by the openInput() function from the parent rootOpts struct.
Output can be directed to a file or stdout:
Output file handling is managed by the openOutput() method at cmd/gobl.cii/convert.go64-67
Both file handles are properly closed using deferred calls at cmd/gobl.cii/convert.go62 and cmd/gobl.cii/convert.go68 ensuring resources are released even if errors occur during processing.
Sources: cmd/gobl.cii/convert.go58-68 cmd/gobl.cii/convert.go70-73
The CLI returns descriptive errors for common failure scenarios:
| Error Type | Example Message | Trigger Condition |
|---|---|---|
| Argument Error | expected one or two arguments, the command usage is... | Wrong number of arguments provided |
| Context Error | unsupported context: invalid_format | Unknown --context value |
| Input Error | reading input: <error> | Cannot read input file |
| Parse Error | parsing input as GOBL Envelope: <error> | Invalid JSON structure |
| Conversion Error | building xrechnung document: <error> | GOBL validation or conversion failure |
| XML Generation Error | generating xrechnung xml: <error> | XML marshaling failure |
| CII Parse Error | converting CII to GOBL: <error> | Invalid XML or unsupported CII features |
| JSON Generation Error | generating JSON output: <error> | JSON marshaling failure |
| Output Error | writing output: <error> | Cannot write to output file |
All errors are wrapped with context using fmt.Errorf with the %w verb to preserve the error chain. This allows upstream callers to inspect underlying errors using errors.Is() or errors.As().
Sources: cmd/gobl.cii/convert.go34-115
Convert a GOBL invoice to the default EN 16931 format:
This uses the default context (en16931), which corresponds to cii.ContextEN16931V2017.
Convert to German XRechnung format:
The output XML will include XRechnung-specific guideline identifiers as defined in cii.ContextXRechnungV3.
Parse a CII XML invoice into GOBL format:
The --context flag is ignored here, as the context is detected from the XML's GuidelineSpecifiedDocumentContextParameter.
Demonstrate bidirectional conversion:
Note that some data loss may occur during round-trip conversion due to semantic differences between GOBL and CII. See Standards Compliance and Limitations for details.
Generate CII documents for different standards from the same GOBL source:
Each output file will contain format-specific guideline IDs and business process parameters.
Sources: README.md116-125
The CLI is built using the spf13/cobra framework, which provides command parsing, flag handling, and help text generation.
Key Components:
convertOpts struct cmd/gobl.cii/convert.go13-16: Holds CLI-specific configuration
*rootOpts for shared functionalitycontext field stores the --context flag valuecmd() method cmd/gobl.cii/convert.go22-32: Creates and configures the cobra command
--context flagrunE handlerrunE() method cmd/gobl.cii/convert.go34-115: Main execution logic
The context resolution uses a simple switch statement cmd/gobl.cii/convert.go41-56:
This mapping ensures the CLI string values (lowercase, user-friendly) are translated to the appropriate package-level Context constants.
Sources: cmd/gobl.cii/convert.go13-115
While this page documents the convert command, the CLI tool may be extended with additional commands in the future. The architecture supports this through cobra's hierarchical command structure.
For validation of generated CII documents, use external tools:
go test ./... -validate (documented in Testing Framework)For batch processing or integration into build pipelines, the CLI can be wrapped in shell scripts or invoked programmatically. For direct Go integration, see Go API Usage.
Sources: README.md107-125
Refresh this wiki