Where the options and arguments are:

run, selects the run command

If the command is omitted, run is assumed.

--configuration:configuration-file, identifies a configuration file

When XML Calabash begins, it reads configuration settings from a configuration file. If you don’t specify a configuration file, it will search first for .xmlcalabash3 in the current directory and then in your home directory.

--pipe:boolean, sets piped mode

If piped mode is enabled, XML Calabash will behave like a Unix pipeline. If there is no binding for the primary input port, it will read it from standard input. If there is no binding for the primary output port, it will write it to standard output. If not specified, the default setting comes from the piped-io configuration setting.

--input:port=uri, identifies an input

This option associates the resource identified by the uri with the input port named port. If the --input option is repeated for the same port, the resources become a sequence of documents on that port, in the order specified.

The pipeline must have an input port named port.

If the input uri provided is “-”, input will be read from standard input. When standard input is read, it will be parsed as the (first) content type listed on the named input port. It will be parsed as XML if the input port doesn’t specify any content types.

--output:port=filespec, identifies an output

In the simplest case, at most one document appears on the output port and filespec is just a filename. The filespec can also be a template. The output documents are numbered, starting at 1. Within the filespec, the string “%d” will be replaced by the document number. (The string “%h” will be replaced by the document number in hexadecimal and “%o” will be replaced by the document number in octal, for no good reason.) Zeros can be added to pad the value, “%00d” will produce a document number that is at least two digits long, padded on the left with 0’s if there are fewer than 10 documents. For completeness, a literal “%” can be added to the filename with “%%” in the filespec.

If the filespec does not contain a number template, then all of the outputs on the port will be concatenated to the same file. You may not repeat the --output option for the same port.

The pipeline must have an output port named port.

If the output filespec provided is “-”, output from that port will be written to standard output. At most one output port may be explicitly bound to standard output.

In piped mode, at most one port will write to standard output. If there is no explicit binding to standard output, the primary output port writes to standard output. If the primary output port is bound to some other output, no output will be sent to standard output.

If piped mode is not enabled, and no port is explicitly bound to standard output, the pipeline will write the output from all otherwise unbound output ports to standard output. If standard output appears to be going to a terminal window:

• A header is printed before the output identifying the port name, document number, and base URI.

• A line of equal signs is printed as a separator between documents (if more than one document is output).

• When XML or HTML content is output, the XML declaration is omitted.

• Indentation is turned on.

The method for determining whether output is going to a terminal or being redirected isn’t terribly sophisticated and may be wrong in some circumstances. It’s safer to use --output to write to a file if you want to save the output or enable piped mode.

--namespace:prefix=uri, identifies a namespace binding

Binds the specified prefix to the uri. This has no effect on the pipeline; these bindings are only used when evaluating the --step option and in expressions used to define options.

The default namespace bindings on the command line are:

Prefix	Namespace URI
array	http://www.w3.org/2005/xpath-functions/array
cx	http://xmlcalabash.com/ns/extensions
fn	http://www.w3.org/2005/xpath-functions
map	http://www.w3.org/2005/xpath-functions/map
math	http://www.w3.org/2005/xpath-functions/math
p	http://www.w3.org/ns/xproc
saxon	http://saxon.sf.net/
xs	http://www.w3.org/2001/XMLSchema

The --namespace option can add to, or change, these bindings.

--init:class-name, Saxon configuration initializer

Attempts to load and execute the class named class-name, which must be available on the class path and must implement the net.sf.saxon.lib.Initializer interface. (This is analagous to the -init: option on the Saxon command line API.)

--graphs:graph-output-directory, SVG graph outputs

This option writes hyperlinked SVG descriptions of pipelines, and their corresponding graphs, to the graph-output-directory. The descriptions are “boxes and arrows” diagrams of the connections between the steps. One SVG diagram is produced for each declared pipeline and its corresponding graph. An HTML index in the graph-output-directory makes them easy to browse. See Chapter 4, Pipelines vs. Graphs for more details.

The processor assumes that it “owns” the graph-output-directory; it will erase files and directories before creating the graph output.

ⓘ

Note

Some browsers have better support for SVG than others. If the diagrams are difficult to view, or if links don’t work correctly, a good first step is to try a different browser.

--verbosity:verbosity

There are five levels of verbosity. The level of verbosity determines how much detail is printed about the progress of a running pipeline.

trace

Lots of detail, show everything.

debug

Lots of detail

info

Show relevant status messages.

warn

Show only warnings and errors.

error

No messages except fatal errors

Setting the verbosity also sets the logging level.

--explain, explain errors

Enables error explanations. If error explanations are enabled, when a pipeline fails, in addition to the error message, a short explanation of the cause will be provided.

--visualizer:name

Selects a visualizer for reporting pipeline progress. There are three defined visualizers.

silent

Shows no progress reports.

plain

Reports the name of each step when it begins running. Most steps manufactured automatically during graph construction are omitted. There is one option, indent which determines whether or not, and to what extent, reports are indented when they are nested inside compound steps.

detail

Reports the name of each step and may report on the documents produced.

If the steps option is true, the progress of steps is recorded. (Defaults to true.)

If the documents option is true, the documents produced during execution are recorded. (Defaults to false.)

Options can be specified on the command line as key=value pairs after the name. The name and any options are separated by a question mark (?). Key-value pairs are separted by semicolons (;). For example: --visualizer=detail?steps=true;documents=true.

--trace:output-file, defines a runtime trace file

A runtime trace of the pipeline execution will be written to output-file. (If the --trace-documents option is given but the --trace option is not, the default output file is named trace.xml in the --trace-documents output directory.)

For more information about tracking, see Appendix B, Tracing execution.

--trace-documents:output-directory, defines a runtime trace directory

If the --trace-documents option is given, the runtime trace will write a copy of every document that flows through the pipeline into the specified directory. These documents are identified in the --trace file.

--assertions:level

By default, assertions are disabled. You can enable them by setting an appropriate level:

error

Schematron reports are output and Schematron errors are treated as errors. (They cause the step to throw Q{http://xmlcalabash.com/ns/error}XI0041.)

warning (or warn)

Schematron reports are output and Schematron errors are treated as warnings.

ignore

Assertions are ignored.

--licensed

Requests a licensed processor. In practice, a licensed processor is used by default, if one is available. However, --licensed:false can be used to explicitly request an unlicensed processor when Saxon PE or Saxon EE are on the classpath.

Schema-aware processing requires Saxon EE and a valid Saxon license.

--debug

If debugging is enabled, the verbosity is set to at least the debug level and the backend logging framework’s “log level” is set to the verbosity.

This produces a lot of messages, typically on the standard error output. XML Calabash uses SLF4J and Logback for logging. You can configure it in the usual ways.

--debugger

Start an interactive debugging session on the pipeline. See Chapter 7, The interactive debugger.

--catalog:catalog-file-uri

Adds the specified catalog to the list of XML Catalogs that are used during resource resolution.

--xml-schema:xml-schema-file-uri

Adds the specified XML Schema to the validation context. This schema will be available in both implicit validation and when the p:validate-with-xml-schema step is used.

--validation-mode:mode

This option enables implicit validation. The mode must be either “lax” or “strict”.

----try-namespaces

This option enables attempting to retrieve a schema using its namespace URI during implicit validation.

--use-location-hints

This option enables attempting to retrieve a schema using location hints during implicit validation.

--help

This is equivalent to issuing the help command. It’s provided as an option for convenience.

--step:step, identifies a step

The --step option is a little bit overloaded. Its interpretation depends on whether or not a pipeline is specified.

If a pipeline is specified, it must identify a p:library. The value of the --step option is interpreted as the name of a step in that library. The named step will be run.

For example:

$ xmlcalabash --step:helloWorld --library:examples.xpl …

If no pipeline is specified, the value of the --step option is interpreted as the type of a step. The (atomic) step with the specified type will be run. All of the inputs, outputs, and options specified apply to that step.

For example:

$ xmlcalabash --step:p:xslt …

The p and cx namespaces are bound by default. The --namespace option can be used to change the namespace bindings.

pipeline.xpl, the pipeline to run

This identifies the pipeline to run. If the root element is p:declare-step, then that pipeline will be run. If the root element is p:library, the first pipeline in the library will be run, unless the step option specifies an alternate pipeline.

option=value, sets an option

You can provide values for pipeline options on the command line. These override any defaults declared in the pipeline. There must be a pipeline option named option.

The option name can be an EQName or it can use a prefix previously defined with --namespace; if the option is a simple NCName, it is not in a namespace.

If the value begins with “?”, what follows is taken to be an XPath expression. That expression is evaluated using the namespace bindings defined. The context item is undefined. The result of evaluating the expression is the value of the option. If the value does not begin with a “?”, the whole string becomes the value as an xs:untypedAtomic.

If multiple assignments to the same option appear, the option’s value will be a sequence with those values in the order specified.

Displays a short summary of the command line options and arguments, not dissimilar to the preceding section. If help is requested, all of the other command line arguments are ignored.

Displays the XML Calabash version and the version of Saxon:

$ xmlcalabash version
XML Calabash version 3.0.0-alpha24 (build 82e681b.193.100f30, 16 Mar 2025)
Running with Saxon HE version 12.5

Most options are ignored when the version command is used, but if the debug level of --verbosity is requested, the version summary will include details about third party dependencies such as the HTML parser and XML resolver. In this case, the output is formatted in a way that can more easily be parsed, for example by a shell script.

$ xmlcalabash --debug
PRODUCT_NAME=XML Calabash
VERSION=3.0.0-alpha24
BUILD_DATE=2025-03-16
BUILD_ID=82e681b.193.100f30
SAXON_EDITION=HE
VENDOR_NAME=Norm Tovey-Walsh
VENDOR_URI=https://xmlcalabash.com/
DEPENDENCY_brotliDec=0.1.2
DEPENDENCY_commonsCodec=1.17.0
DEPENDENCY_commonsCompress=1.27.1
DEPENDENCY_flexmarkAll=0.64.8
DEPENDENCY_graalvmJS=23.1.5
DEPENDENCY_htmlparser=1.4.16
DEPENDENCY_httpClient=5.3.1
DEPENDENCY_jing=20241231
DEPENDENCY_jsonSchemaValidator=1.5.4
DEPENDENCY_saxon=12.5
DEPENDENCY_schxslt2=1.3.1
DEPENDENCY_sinclude=5.3.0
DEPENDENCY_slf4j=2.0.16
DEPENDENCY_tukaaniXz=1.10
DEPENDENCY_uuidCreator=6.0.0
DEPENDENCY_xercesImpl=2.12.2
DEPENDENCY_xmlResolver=6.0.12