CLI Tool

Relevant source files

• LICENSE
• README.md
• go.mod
• go.sum

The CLI tool provides a command-line interface for bidirectional conversion between GOBL JSON and UBL XML formats. It wraps the core conversion API (documented in Core API Functions) in an easy-to-use command that automatically detects input format and performs the appropriate transformation.

This document covers the command-line tool implementation, command structure, and usage patterns. For information about the underlying conversion logic, see Conversion System. For details on the Go package API, see Core API Functions.

---

Installation and Setup

The CLI tool is installed as a Go binary using the standard Go toolchain:

This compiles the command located in cmd/gobl.ubl and installs it as gobl.ubl in the user's $GOPATH/bin directory. The tool requires Go 1.24.4 or later as specified in go.mod3

Sources: README.md114-118 go.mod3

---

Command Structure

The CLI tool uses the Cobra framework (v1.9.1) to implement its command structure. The tool provides a single primary command with automatic format detection.

The command structure consists of:

Component	Type	Location	Purpose
convertOpts	struct	cmd/gobl.ubl/convert.go13-15	Holds command configuration and options
cmd()	method	cmd/gobl.ubl/convert.go21-29	Creates and configures the Cobra command
runE()	method	cmd/gobl.ubl/convert.go31-91	Implements the conversion execution logic

Sources: cmd/gobl.ubl/convert.go1-92 go.mod8

---

Command Usage

The convert command accepts one or two arguments:

Parameters:

Parameter	Required	Description
<infile>	Yes	Input file path (JSON or XML) or - for stdin
[outfile]	No	Output file path or - for stdout (defaults to stdout)

Usage Examples:

The command validates argument count at cmd/gobl.ubl/convert.go32-34 and returns an error if zero or more than two arguments are provided.

Sources: cmd/gobl.ubl/convert.go22-25 README.md127-129

---

Automatic Format Detection

The CLI tool automatically determines whether the input is GOBL JSON or UBL XML, eliminating the need for explicit format flags. This detection occurs at cmd/gobl.ubl/convert.go54

Detection Logic:

The format detection uses the standard library's json.Valid() function which performs a complete JSON syntax validation:

Condition	Format	Conversion Path
json.Valid() returns true	GOBL JSON	JSON → XML (lines 58-71)
json.Valid() returns false	UBL XML	XML → JSON (lines 73-83)

This approach is simple but reliable: any valid JSON input is treated as GOBL, while invalid JSON is assumed to be XML. The subsequent parsing step will fail gracefully if the format assumption is incorrect.

Sources: cmd/gobl.ubl/convert.go48-84

---

Conversion Workflows

GOBL to UBL Conversion (JSON → XML)

When JSON input is detected, the tool executes the GOBL to UBL conversion pipeline:

Process Steps:

Step	Function	Lines	Description
1. Allocate	new(gobl.Envelope)	59	Create empty GOBL envelope
2. Parse	json.Unmarshal()	60-62	Deserialize JSON into envelope
3. Convert	ubl.ConvertInvoice()	63-66	Transform GOBL to UBL structure
4. Serialize	ubl.Bytes()	68-71	Marshal UBL to XML bytes

Error Handling:

Each step includes error checking and wrapping with context:

• Parse error: "parsing input as GOBL Envelope" (line 61)
• Convert error: "building UBL document" (line 65)
• Serialize error: "generating UBL xml" (line 70)

Sources: cmd/gobl.ubl/convert.go58-71

---

UBL to GOBL Conversion (XML → JSON)

When XML input is detected, the tool executes the UBL to GOBL conversion pipeline:

Process Steps:

Step	Function	Lines	Description
1. Parse & Convert	ubl.Parse()	75-78	Parse XML and convert to GOBL (combined)
2. Serialize	json.MarshalIndent()	80-83	Format GOBL as pretty-printed JSON

Important Note: Unlike the GOBL→UBL path, the ubl.Parse() function returns a *gobl.Envelope directly (not a UBL document). The conversion from UBL to GOBL happens internally during parsing, as documented in UBL to GOBL Parsing.

Error Handling:

• Parse error: "building GOBL envelope" (line 77)
• Serialize error: "generating JSON output" (line 82)

Sources: cmd/gobl.ubl/convert.go73-83

---

File I/O Handling

The CLI tool supports flexible input/output handling through the openInput() and openOutput() helper functions referenced at cmd/gobl.ubl/convert.go36 and cmd/gobl.ubl/convert.go42

Input Sources

The tool accepts input from:

Source	Argument	Behavior
File	./path/to/file.json	Opens and reads the specified file
Stdin	- or no argument	Reads from standard input for pipeline operations

Input handling occurs at cmd/gobl.ubl/convert.go36-40:

The entire input is read into memory using io.ReadAll() at cmd/gobl.ubl/convert.go48-51 This is acceptable for document conversion as invoice files are typically small (< 1MB).

Output Destinations

The tool writes output to:

Destination	Argument	Behavior
File	./path/to/output.xml	Creates/overwrites the specified file
Stdout	No second argument or -	Writes to standard output

Output handling occurs at cmd/gobl.ubl/convert.go42-46:

Output is written in a single operation at cmd/gobl.ubl/convert.go86-88:

Sources: cmd/gobl.ubl/convert.go36-88

---

Error Handling

The CLI tool implements comprehensive error handling with contextual error messages using Go's error wrapping with fmt.Errorf() and the %w verb.

Error Categories

Error Messages

Each error is wrapped with a descriptive context string:

Error Source	Context Message	Lines
Argument validation	"expected one or two arguments..."	33
Input reading	"reading input"	50
GOBL parsing	"parsing input as GOBL Envelope"	61
UBL generation	"building UBL document"	65
XML serialization	"generating UBL xml"	70
UBL parsing	"building GOBL envelope"	77
JSON serialization	"generating JSON output"	82
Output writing	"writing output"	87

All errors are returned to the Cobra framework through the RunE function signature at cmd/gobl.ubl/convert.go25 which handles displaying them to the user and setting appropriate exit codes.

Sources: cmd/gobl.ubl/convert.go32-91

---

Integration with Core API

The CLI tool serves as a thin wrapper around the core conversion API. It delegates all conversion logic to the library functions documented in Core API Functions.

API Function Mapping

Responsibilities

The CLI tool handles:

• Command-line argument parsing (lines 32-34)
• File I/O operations (lines 36-46, 48-51, 86-88)
• Format detection (line 54)
• Error message formatting (lines 50, 61, 65, 70, 77, 82, 87)

The core API handles:

• GOBL envelope validation and addon requirements (via ubl.ConvertInvoice())
• UBL document structure generation (via ubl.ConvertInvoice())
• XML marshaling with proper namespaces (via ubl.Bytes())
• UBL XML parsing and document type detection (via ubl.Parse())
• GOBL envelope creation from UBL data (via ubl.Parse())

This separation allows the CLI to remain simple while the complex conversion logic is thoroughly tested in the library layer, as documented in Test Framework.

Sources: cmd/gobl.ubl/convert.go58-83 README.md23-110

---

Dependencies

The CLI tool relies on the following dependencies declared in go.mod:

Package	Version	Purpose	Lines
github.com/spf13/cobra	v1.9.1	Command-line framework	8
github.com/invopop/gobl	v0.305.0	GOBL core types	6
github.com/invopop/gobl.ubl	(current)	Conversion library	N/A

The tool uses standard library packages extensively:

• encoding/json - JSON parsing and serialization
• io - Stream reading (io.ReadAll)
• fmt - Error formatting
• os - File operations (via openInput/openOutput)

Sources: go.mod5-11 cmd/gobl.ubl/convert.go3-11