CLI Tool (cmd/helium)

Relevant source files

• .claude/docs/helium-command.md
• cmd/helium/README.md
• cmd/helium/main.go

The helium command-line tool provides a unified interface for XML processing, mirroring the functionality of traditional toolkits like libxml2's xmllint and xsltproc. It integrates the various sub-packages of the helium project—including the core parser, XPath engines (1.0 and 3.1), XSLT 3.0 transformer, and multiple schema validation engines—into a single binary.

The CLI is designed for both interactive use and automated pipelines, featuring robust TTY detection, standardized exit codes, and support for streaming input via stdin.

---

System Architecture: CLI to Core Integration

The CLI entrypoint is located in cmd/helium/main.go, which simply delegates execution to the implementation package internal/cli/heliumcmd. This implementation package contains all the logic for each sub-command, orchestrating the interactions with the core helium packages responsible for parsing, XPath evaluation, validation, and transformation.

The diagram below illustrates how the cmd/helium command delegates work to internal/cli/heliumcmd subcommand implementations, which in turn use the underlying sub-packages for XML processing:

CLI Component Orchestration

Sources: cmd/helium/main.go10-12 .claude/docs/helium-command.md1-23

---

Sub-commands Overview

The helium CLI tool organizes XML processing into several primary sub-commands, each specializing in an XML processing facet. These sub-commands expose options and flags tailored to their respective domain:

Command	Primary Package	Purpose
lint	helium	Parses and lints XML documents with xmllint-style flags, including XInclude and canonicalization support.
xpath	xpath3 / xpath1	Evaluates XPath expressions against XML input; supports selection of XPath 1.0 or 3.1 engines.
xsd validate	xsd	Validates XML documents against a W3C XML Schema (XSD).
relaxng validate	relaxng	Validates XML against a RELAX NG schema.
schematron validate	schematron	Validates XML documents against ISO Schematron rules.
xslt	xslt3	Applies XSLT 3.0 stylesheets to XML documents.

For complete command usage, flags, exit codes, and behavior details, see the child page CLI Sub-commands and Usage.

Sources: .claude/docs/helium-command.md16-23 cmd/helium/README.md10-17

---

Implementation and Lifecycle

All CLI logic is implemented in the internal/cli/heliumcmd package, which exposes a simple API entrypoint:

• heliumcmd.Execute(ctx, args) runs the CLI with the specified arguments internal/cli/heliumcmd/heliumcmd.go29-31
• heliumcmd.WithIO(ctx, stdin, stdout, stderr) and heliumcmd.WithStdinTTY(ctx, bool) provide testing hooks by overriding standard I/O streams and TTY detection internal/cli/heliumcmd/heliumcmd.go33-40

Sub-command implementations follow a common lifecycle pattern:

• Schema or stylesheet compilation occurs once (e.g., xsd.NewCompiler().CompileFile, xslt3.NewCompiler().Compile).
• Each input XML file is parsed independently.
• Validation or transformation is executed per input.
• Results are output or errors handled accordingly.

This approach optimizes batch processing by avoiding redundant schema or stylesheet recompilation.

Validation Lifecycle Example

The helium lint command implements a multi-stage processing pipeline, which includes reading, parsing, XInclude processing, schema validation, DTD validation, XPath evaluation, and various output options like C14N or standard XML serialization. This pipeline ensures that multiple XML processing steps can be applied in a single command invocation.

Lint Command Processing Pipeline

Sources: .claude/docs/helium-command.md7-138

For detailed implementation mechanics, including pipeline stages and exit code definitions, see CLI Implementation (heliumcmd).

---

Exit Codes and Status Reporting

The CLI defines standardized exit codes to communicate operation outcomes and facilitate scripting:

Exit Code	Constant	Meaning
0	ExitOK	Success
1	ExitErr	Generic or usage error
3	ExitValidation	Validation failed
4	ExitReadFile	File or stdin read error
5	ExitSchemaComp	Schema compilation error
10	ExitXPath	XPath compile/evaluation error
11	ExitXSLT	XSLT compile or transform error

When processing multiple XML inputs in a single run, the CLI exits with the highest error code encountered internal/cli/heliumcmd/exitcode.go20-30

Sources: .claude/docs/helium-command.md25-37

---

Input and I/O Handling

The CLI follows consistent and predictable input handling rules:

• Primary resource arguments: For commands like validation and transformation, the first positional argument is a required resource path—schema or stylesheet.
• XML inputs: Subsequent positional arguments are treated as XML input files.
• Standard input fallback: If no XML files are given and input is piped (non-TTY), XML is read from stdin.
• TTY-based usage output: If required XML inputs are missing and stdin is a TTY, the CLI prints usage information and exits with ExitErr (1).

Example rules per sub-command:

Command	Required Positional Arg	XML Input Files
helium lint	None	Files if given, else stdin if piped
helium xpath	Expression (first positional)	Files or stdin if none
helium xsd validate	Schema path	Files or stdin if none
helium relaxng validate	Schema path	Files or stdin if none
helium schematron validate	Schema path	Files or stdin if none
helium xslt	Stylesheet path	Files or stdin if none

The CLI supports injecting custom input/output streams and overriding TTY detection (via heliumcmd.WithIO and heliumcmd.WithStdinTTY) primarily for automated testing.

A critical safety feature for output files is implemented using a write-to-temp-then-atomic-rename scheme (pendingOutput in safety.go). This prevents data loss by ensuring that output files are only committed after all processing is successful and avoids truncating input files that might also be designated as output. This mechanism handles symlinks and checks for write permissions on existing files to prevent accidental overwrites of read-only or non-regular files.

Sources: .claude/docs/helium-command.md39-78

---

Summary

The helium CLI tool serves as the front door to the entire helium XML processing ecosystem. It cleanly integrates parsing, various XPath engines, schema validation methods, and XSLT 3.0 transformation under a single interface, managing resource lifecycle and I/O with robust defaults and testability in mind.

Detailed documentation of individual sub-commands and their usage are provided in the child page CLI Sub-commands and Usage. For in-depth explanation of the CLI’s internal mechanics and execution flow, see CLI Implementation (heliumcmd).

---

Sources:
cmd/helium/main.go10-12
.claude/docs/helium-command.md1-138
cmd/helium/README.md1-82