Command-Line Interface

Relevant source files

• .goreleaser.yml
• cmd/gobl.cfdi/main.go
• cmd/gobl.cfdi/root.go

Purpose and Scope

This document describes the gobl.cfdi command-line interface tool, which provides a user-facing interface for converting GOBL invoices to CFDI XML format and parsing existing CFDI documents. The CLI serves as the primary entry point for users who need to perform CFDI conversions without writing Go code.

For information about the programmatic conversion API, see Core CFDI Engine. For build system configuration and local development, see Build System. For automated release processes, see CI/CD Pipeline.

---

CLI Architecture and Entry Point

The gobl.cfdi CLI is built using the Cobra framework, which provides a command structure, flag parsing, and help documentation generation. The application entry point is located in cmd/gobl.cfdi/main.go

Application Lifecycle

CLI Application Flow

The main application flow follows a structured initialization pattern:

1. Signal Handling Setup - cmd/gobl.cfdi/main.go30 creates a context that responds to SIGINT and SIGTERM signals, enabling graceful shutdown when users press Ctrl+C or when the process receives termination signals.

2. Environment Loading - cmd/gobl.cfdi/main.go33-37 attempts to load a .env file if present in the current directory, allowing users to configure behavior through environment variables without exposing them on the command line.

3. Command Execution - cmd/gobl.cfdi/main.go39 executes the root Cobra command with the cancellable context.

Build Metadata

The CLI embeds version information through build-time variables:

Variable	Purpose	Default	Source
name	Binary name	gobl.cfdi	cmd/gobl.cfdi/main.go17
version	Release version	dev	cmd/gobl.cfdi/main.go18
date	Build date	""	cmd/gobl.cfdi/main.go19

These variables are populated by the build system (see Build System) through -ldflags during compilation, enabling the version command to report accurate build information.

Sources: cmd/gobl.cfdi/main.go1-48

---

Command Structure

The CLI provides a root command with three subcommands, organized through the rootOpts structure and Cobra command tree.

Command Hierarchy

Root Command Configuration

The root command is configured with minimal options through the rootOpts struct cmd/gobl.cfdi/root.go10-11:

The cmd() method cmd/gobl.cfdi/root.go17-29 constructs the root command and attaches subcommands:

• versionCmd() - Returns version and build information
• convert(o).cmd() - Converts GOBL invoices to CFDI XML format
• parse(o).cmd() - Parses CFDI XML back to GOBL format

Both SilenceUsage and SilenceErrors are enabled cmd/gobl.cfdi/root.go20-21 allowing the application to control error output formatting rather than relying on Cobra's default behavior.

Subcommand Structure

Each subcommand follows a consistent pattern:

1. Takes rootOpts as a parameter to access shared functionality
2. Returns a struct with a cmd() method that produces a *cobra.Command
3. Implements command-specific logic while delegating I/O handling to root helpers

Sources: cmd/gobl.cfdi/root.go1-58

---

Input/Output Handling

The CLI implements flexible I/O handling that supports both file-based operations and stream-based operations through stdin/stdout. This design enables pipeline composition and integration with other Unix tools.

I/O Resolution Pattern

Input Handling

The openInput() function cmd/gobl.cfdi/root.go38-43 implements a standard Unix convention:

Argument Value	Behavior	Implementation
File path	Opens specified file	os.Open(inFile)
-	Reads from stdin	cmd.InOrStdin()
Omitted	Reads from stdin	cmd.InOrStdin()

The inputFilename() helper cmd/gobl.cfdi/main.go42-47 extracts the input filename from command arguments, returning an empty string if the first argument is - or if no arguments are provided.

Output Handling

The openOutput() method cmd/gobl.cfdi/root.go45-51 follows a parallel pattern:

Argument Value	Behavior	Implementation
File path	Creates/overwrites file	os.OpenFile() with O_CREATE|O_WRONLY
-	Writes to stdout	cmd.OutOrStdout()
Omitted	Writes to stdout	cmd.OutOrStdout()

The outputFilename() method cmd/gobl.cfdi/root.go31-36 extracts the output filename from the second command argument.

WriteCloser Adapter

To provide a uniform io.WriteCloser interface for both files and stdout, the code implements a simple adapter cmd/gobl.cfdi/root.go53-57:

This allows command implementations to treat all outputs uniformly, calling Close() without checking whether the underlying writer is a file or a stream.

Pipeline Examples

The flexible I/O design enables various usage patterns:

Sources: cmd/gobl.cfdi/root.go31-58 cmd/gobl.cfdi/main.go42-47

---

Signal Handling and Context Management

The CLI implements graceful shutdown through Go's context cancellation mechanism, ensuring that long-running operations can be interrupted cleanly.

Context-Based Cancellation

Signal Registration

The run() function cmd/gobl.cfdi/main.go30-31 creates a context that automatically cancels when receiving specific Unix signals:

• SIGINT (syscall.SIGINT) - Generated by Ctrl+C in terminal
• SIGTERM (syscall.SIGTERM) - Standard termination signal from process managers

The defer cancel() ensures that resources are cleaned up when run() exits, even if command execution completes normally.

Context Propagation

The cancelled context is passed to Cobra's ExecuteContext() cmd/gobl.cfdi/main.go39 which makes it available to all command implementations through cmd.Context(). This enables commands to:

1. Check for cancellation during long-running operations
2. Pass the context to underlying APIs (e.g., HTTP clients, database connections)
3. Exit gracefully without leaving partial output

Environment Configuration

Before executing commands, the CLI attempts to load environment variables from a .env file cmd/gobl.cfdi/main.go33-37:

This pattern:

• Loads variables if .env exists
• Ignores os.ErrNotExist (no file present)
• Returns an error for other failures (e.g., permission denied, parse errors)

This allows users to configure sensitive information (like API credentials) without exposing them in shell history or process listings.

Sources: cmd/gobl.cfdi/main.go29-40

---

Distribution and Binary Artifacts

The CLI is distributed as a standalone binary compiled for multiple platforms through GoReleaser configuration.

Build Targets

The .goreleaser.yml configuration .goreleaser.yml4-13 defines the build matrix:

Configuration	Value
Build ID	gobl.cfdi
CGO	Disabled (CGO_ENABLED=0)
Target OS	Linux, Windows, Darwin (macOS)
Source Path	./cmd/gobl.cfdi
Binary Name	gobl.cfdi

Disabling CGO ensures that the binary is fully static and can run on any system without external dependencies.

Archive Structure

Release archives .goreleaser.yml15-21 follow a consistent naming convention:

gobl.cfdi_<version>_<os>_<arch>.tar.gz

Each archive:

• Contains the gobl.cfdi binary wrapped in a directory
• Includes checksums in checksums.txt .goreleaser.yml23-24
• Uses tar.gz format for compression

Release Process

The release workflow .goreleaser.yml33-37 is configured to:

1. Publish to the invopop/gobl.cfdi GitHub repository
2. Automatically determine pre-release status
3. Generate a changelog excluding documentation and test commits .goreleaser.yml27-31

For detailed information on the release automation, see CI/CD Pipeline.

Binary Distribution Flow

Sources: .goreleaser.yml1-38

---

Error Handling and Exit Codes

The CLI implements a consistent error handling pattern that provides clear feedback to users and proper exit codes for shell scripting.

Error Flow

Error Handling Pattern

The main() function cmd/gobl.cfdi/main.go22-27 delegates to run() and handles any returned error by:

1. Writing the error message to stderr cmd/gobl.cfdi/main.go24
2. Exiting with status code 1 cmd/gobl.cfdi/main.go25

This pattern ensures:

• Clean separation between business logic and process termination
• Proper error visibility in shell pipelines
• Standard Unix exit code conventions (0 = success, non-zero = failure)

Cobra Error Suppression

The root command disables Cobra's default error handling cmd/gobl.cfdi/root.go20-21 through:

• SilenceUsage: true - Prevents usage text from appearing on errors
• SilenceErrors: true - Prevents Cobra from printing errors automatically

This gives the application full control over error formatting and output, ensuring consistent error messages across all commands.

Sources: cmd/gobl.cfdi/main.go22-27 cmd/gobl.cfdi/root.go17-29