FreeBSD libxo: Design Stable Structured Output for CLI Automation

FreeBSD’s libxo lets a program render the same semantic fields as terminal text, XML, JSON, or HTML. This is valuable for administrative tooling because scripts can consume structured output without guessing column widths or splitting human-oriented lines. It is not a universal machine-output switch: only applications built to use libxo recognize its options, and every program has to describe its output fields intentionally.

The production benefit comes from treating output as an interface. A line of text can be reformatted for readability without preserving a parser contract, while a named field such as packets or interface has explicit structure. A robust automation workflow first checks whether a given base command supports libxo, selects one output style, validates the result, and pins assumptions to the command’s documented schema. It should still handle command failure, missing values, and changes across FreeBSD releases.

Identify the actual libxo surface

libxo is a library and a family of command-line options, not an output mode automatically available to every utility. The FreeBSD manuals describe common options such as -J or –libxo=json for JSON, -T for text, -X for XML, and -H for HTML. Before building automation around one command, read that command’s own manual and check its output options on the target release:

man xo_options
man netstat
man ifconfig
man jls

The commands above are discovery prompts, not a guarantee that each one accepts identical flags or emits the same data. Some commands use libxo, some have separate JSON options, and others expose only human-readable output. For a libxo-based command, its manual normally documents the supported style flags and any formatting differences. Check the version shipped on each managed host rather than assuming a newer manual applies unchanged to an older release.

Avoid discovering support by passing a production command arbitrary undocumented flags. Some programs interpret unknown options in surprising ways. Use the manual page installed for the binary, its documented help output, and a safe read-only invocation. If the utility has no structured mode, either consume a documented stable format from another interface or write a small adapter with explicit validation. Do not label regex scraping as a reliable API.

Understand the field model before parsing JSON

libxo’s format strings associate human-readable presentation with field names. Its documented examples use descriptors such as {:lines/%7ju}, where lines is the field identity and the percent expression controls text formatting. The field name is the key for structured output; the display format and labels can differ by style. Lists, instances, containers, and detail fields help create a hierarchy that maps to JSON or XML while retaining a readable text view.

This separation is important when consuming output. A parser should select fields by their documented names, not by the order in which they happen to appear. It should tolerate additive fields if the interface promises extensibility, reject missing fields that the task requires, and explicitly handle null or absent values. A JSON parser can prove that the output is syntactically valid; it cannot prove that the field has the expected unit, scope, or semantics.

Try a supported utility in JSON mode and inspect the result before scripting against it:

jls -J
netstat -J

These invocations are examples only if the corresponding installed manual documents -J. Confirm options first on the exact FreeBSD version. If a command uses the long form instead, use the form in its manual. Do not pipe a state-changing command to a parser as an experiment; choose an inventory or status command whose effects are read-only.

Structured mode can still include warnings or diagnostics on standard error. Capture exit status separately from standard output. A successful JSON parse after a nonzero command exit does not make the inventory complete, and an empty JSON document may mean there were no records, that a command failed before output, or that the selected style was not recognized. Define which of those cases should be accepted.

Add libxo to a small C utility

A program using libxo calls xo_parse_args early so the library can consume and remove its own style options before the application parses its remaining arguments. It emits named fields and must call xo_finish before exiting so buffered non-text output is complete. This minimal example uses fixed sample data, which keeps the example independent of device enumeration:

#include <libxo/xo.h>
#include <stdlib.h>

int
main(int argc, char **argv)
{
    const char *interface = "em0";
    unsigned packets = 7;

    argc = xo_parse_args(argc, argv);
    if (argc < 0)
        return (EXIT_FAILURE);

    xo_open_container("interface");
    xo_emit("{:name/%s}{:packets/%u}\n", interface, packets);
    xo_close_container("interface");
    xo_finish();
    return (EXIT_SUCCESS);
}

On FreeBSD, compile this example against the base-system libxo with cc sample.c -lxo -o sample, then exercise the default text output and the documented JSON option:

./sample
./sample --libxo=json

The first call to xo_parse_args returns the adjusted argument count or a negative value on failure. A real program must preserve and process the remaining application arguments; this sample intentionally has none. The container gives the output a hierarchy, the field names name and packets are machine-facing keys, and the format conversions control text rendering. Keep format conversions consistent with the actual C argument types, and use the field-format manual for modifiers rather than relying on printf folklore.

For a production CLI, use xo_set_program when you need libxo diagnostics to identify the application, and use the appropriate error-reporting functions for messages that must adapt to the selected style. Avoid mixing arbitrary printf output into a JSON stream: one stray line on standard output makes the entire document invalid. Send debug traces to standard error or to a logging facility. Test error paths as carefully as success paths, because early returns that omit xo_finish can leave malformed output.

Validate output as a contract

When an output mode is introduced, create a small golden fixture or a schema check for the fields the automation depends on. Verify that numeric counters remain numbers, identifiers remain strings, lists retain their intended nesting, and units or timestamps are not silently lost. If a CLI’s JSON field names change between releases, handle supported versions intentionally instead of treating every parse error as an empty result.

On FreeBSD, save output and use a parser available on the system or in the managed tooling environment. For an installed jq package, a basic parse check is:

command -v jq
jls -J | jq .

The command is appropriate only after confirming jls documents -J and jq is installed. For automation, prefer a specific selection such as checking that the top-level value is the expected array or object and that required keys have the expected types. Do not make the pretty-printed jq output an input contract for another script; it is for inspection.

Test no-record output, one-record output, multiple records, names containing spaces or punctuation, and command failure. For a monitoring collector, distinguish a healthy zero count from a missing field or a failed query. Capture the FreeBSD release, command path, command version if provided, arguments, exit status, parser version, and a sanitized sample. This makes a later discrepancy reproducible.

Avoid the common automation traps

First, do not assume all base utilities support libxo. Second, do not parse terminal tables after structured output has been enabled; the column layout and labels are intended for people and can vary. Third, do not hard-code array ordering unless the manual promises an order. Fourth, do not mix multiple libxo styles in a single invocation. Fifth, do not suppress standard error before you have decided how errors will be surfaced. A successful command can still provide warnings that are operationally important.

A structured output mode also does not promise that the source data is atomic. An inventory command can sample kernel state while interfaces or jails are changing. If the result drives a configuration action, revalidate the target and its state before applying the change. Keep collection read-only, retain a timestamp, and treat the output as a point-in-time observation rather than an enduring truth.

Use a versioned contract for internal scripts. Document command, option, field names, expected types, release range, and failure behavior. Build compatibility tests against each supported FreeBSD release image. If a utility does not have a stable documented output format, either contribute libxo support upstream or expose a small local command that deliberately owns the output contract. Avoid broad sed or awk transformations that hide a schema change.

Acceptance criteria

An implementation is ready when the chosen command documents its structured mode on every target release, the JSON or XML output parses, fields have the expected types and meaning, and errors remain visible without corrupting standard output. For a new libxo utility, demonstrate both default text and structured output, test option parsing with application arguments, and ensure xo_finish executes on success and failure paths.

Record the program and library versions, sample output, validation command, and parser contract. Keep one human-readable mode for interactive use and one structured mode for automation, both driven from the same semantic field definitions. This preserves the strength of libxo: a useful terminal experience without making operators depend on terminal formatting as an undocumented API.

Related:

Sources: