Overview

Xorq provides command-line tools for building, running, serving, and cataloging your data and ML pipelines.

Commands

Project setup

Command	Description
init	Scaffold a new Xorq project from a template.
completion	Print a shell-completion script to stdout.
install-completion	Install the shell-completion script to the standard location.

Build

Command	Description
build	Compile a Xorq expression into a reusable build artifact.
uv build	Build an expression inside a uv-managed isolated environment.

Run

Command	Description
run	Execute a build artifact and write results in your chosen format.
uv run	Execute a build inside a uv-managed isolated environment.
run-cached	Run a build with a parquet cache wrapping the expression.
uv run-cached	Run a build with a parquet cache inside a uv-managed environment.
run-unbound	Run an unbound expression by streaming Arrow IPC input.
uv run-unbound	Run an unbound expression over Arrow IPC inside a uv-managed environment.

Serve

Command	Description
serve-flight-udxf	Serve an expression’s UDXF nodes as an Arrow Flight endpoint.
serve-unbound	Serve an unbound expression as an Arrow Flight endpoint.

Catalog

Manage Xorq build-artifact catalogs.

A catalog is a versioned store of named, sharable, executable expressions: a git repository with an optional object-store backed annex for content. Group options select which catalog a subcommand targets and precede the subcommand name (for example, xorq catalog -n analytics info).

Option	Default	Description
-n, --name	none	Catalog name (mutually exclusive with –path).
-p, --path	none	Catalog repo path (mutually exclusive with –name).
-u, --url	none	Remote repo URL to clone.
-r, --root-repo	none	Repo root to add this catalog to as a submodule.
--init / --no-init	auto	Initialize the repo.

Repo lifecycle

Command	Description
catalog init	Create a new catalog repository.
catalog clone	Clone an existing catalog from a remote URL.
catalog info	Show catalog summary metadata.
catalog default	Show or change the persisted default catalog name.
catalog tui	Browse the catalog interactively in a terminal UI.

Entries and aliases

Command	Description
catalog add	Add entries from build directories or archive files.
catalog remove	Remove entries by name.
catalog list	List all entries.
catalog show	Show full metadata for a catalog entry.
catalog schema	Show the schemas for a catalog entry.
catalog get	Export an entry’s archive to a directory.
catalog add-alias	Attach an alias to an existing entry.
catalog remove-alias	Remove one or more aliases.
catalog list-aliases	List all aliases.

Composition and execution

Command	Description
catalog compose	Compose entries into a new expression and persist it to the catalog.
catalog run	Compose and execute catalog entries, writing data to disk or stdout.
catalog run-cached	Compose and execute catalog entries with a parquet cache wrapper.
catalog serve-unbound	Resolve a catalog entry, unbind a node, and serve it via Flight.

Sync, audit, replay

Command	Description
catalog push	Push the catalog’s commits and annex content to its remotes.
catalog pull	Pull the catalog’s commits and annex content from its remotes.
catalog sync	Pull then push.
catalog set-remote	Configure the catalog’s git remote.
catalog embed-readonly	Embed read-only S3 credentials into the catalog’s git-annex branch.
catalog check	Validate the catalog for consistency.
catalog gc	Remove orphaned content store objects (pointer backend only).
catalog log	Show the catalog’s history as structured operations.
catalog replay	Replay the catalog’s operation log into a target catalog.