xtraqxtraq
Commands

build

Executes code generation based on current configuration. Generates runtime artefacts (table types, procedure wrappers, DbContext helpers) using the metadata stored under `.xtraq/snapshots/`. JSON helpers ship enabled by default—no preview flags required.

Usage

xtraq build [options]

Requirements

  • A tracked .xtraqconfig generated by xtraq init. The command fails fast with guidance to initialise if the file is missing or invalid.
  • Snapshot metadata under .xtraq/snapshots/. Invoke xtraq build --refresh-snapshot (the default when running plain xtraq) to capture metadata automatically.
  • XTRAQ_GENERATOR_DB available via environment variables or .env only when a snapshot refresh is requested.

Command-Specific Options

OptionDescription
--refresh-snapshotRefreshes the snapshot before generating code (equivalent to running xtraq snapshot).

Combine the command with global flags from the CLI overview when needed:

  • -p, --project-path selects another project root.
  • --procedure <schema.proc> scopes work to selected stored procedures.
  • --telemetry persists timing data to .xtraq/telemetry/build-*.json.
  • --ci forces plain-text output, -v/--verbose prints detailed phase messages.

Behavior Contract

AspectDetails
Invocationxtraq build or bare xtraq (implicit --refresh-snapshot).
Reads.xtraqconfig, .xtraq/snapshots/**/*.json, template files under src/Templates/, optional .env when refreshing snapshots.
WritesGenerated artefacts beneath <OutputDir> (defaults to Xtraq/) plus telemetry files when --telemetry is enabled.
Exit codes0 success; non-zero indicates validation/setup issues (missing config or snapshot) or generation failures bubbled from the runtime.
Preconditions.xtraqconfig must resolve; snapshot metadata must exist unless --refresh-snapshot is supplied; when refresh is requested a database connection is required.
Side effectsSchedules a background update check unless disabled; outside CI it prompts to apply the update when one is available; writes telemetry summaries when --telemetry is specified.

Examples

# Generate artifacts for the current directory
xtraq build

# Target a sandbox project configured under debug/
xtraq build -p debug --verbose

# Refresh metadata and build in one step
xtraq build --refresh-snapshot --telemetry

snapshot

Synchronizes stored procedures, parameters, and schema metadata into `.xtraq/` using the connection defined in your `.env` file.

version

Prints the currently installed xtraq tool version and checks for the latest published package.