CLI Overview

Overview of xtraq command-line interface and global options. The xtraq CLI uses a dual-file configuration model anchored on the tracked `.xtraqconfig` snapshot. Secrets remain outside of source control (typically in `.env` or environment variables). Run `xtraq init` once to scaffold both files, then reuse them across `snapshot`, `build`, and the default `xtraq` entry point.

Global Options

Option	Description
`-p, --project-path <project-path>`	Override the working directory (never climbs to parent folders; init will run if the folder lacks `.xtraqconfig`).
`-v, --verbose`	Emit detailed logging (pipeline steps, timings, cache hints).
`--debug`	Use the debug environment wiring for additional diagnostics.
`--no-cache`	Skip cached metadata (forces a full snapshot refresh).
`--procedure <schema.proc>`	Limit snapshot/build operations to matching stored procedures (comma separated, wildcards supported).
`--telemetry`	Persist a detailed database telemetry report for the executed command under `.xtraq/telemetry`.
`--ci`	Switch console output to CI-friendly mode (plain progress, no ANSI art).

--debug-alias exists for internal debugging and is intentionally undocumented for the first public release.

Table-type request validation always relies on the generated DataAnnotations. The former CLI preview flag has been removed, so no additional switch is required.

Telemetry

Telemetry strictly opt-in. Nothing is recorded unless you pass --telemetry.

Append --telemetry to snapshot, build, or the default entry point to capture database query traces, build statistics, and a CLI command summary.
Reports land in .xtraq/telemetry as timestamped JSON files (cli-command-*.json, snapshot-*.json, build-*.json, and optional summaries) that stay on disk until you delete them.
No environment variables or consent banners are involved anymore—omit the switch and the directory remains untouched.
Telemetry files never leave your machine unless you share them manually. See CLI Telemetry Alignment for the current rollout plan.

Core Commands

Command	Purpose
`xtraq`	Default entry point: refresh snapshot and build artefacts in one step (alias for `build --refresh-snapshot`).
`init`	Bootstrap `.xtraqconfig` and optional `.env` secrets.
`snapshot`	Read stored procedures and schema metadata into `.xtraq/` using configured credentials.
`build`	Generate runtime artefacts (table types, helpers) from the current snapshot.
`version`	Display installed and latest CLI versions, including update hints.
`update`	Update the xtraq global tool to the latest available package.

Examples

xtraq init --connection "Server=.;Database=AppDb;Trusted_Connection=True;"
xtraq build

Edit this pageorReport an issue

Migrating from SpocR to Xtraq

High-level guide for replacing legacy SpocR-generated artefacts with Xtraq pipelines in an existing solution. Written for teams that want a clean cut-over path without project-specific assumptions.

xtraq (default command)

Default invocation behaviour when no subcommand is supplied. Running the CLI without an explicit subcommand is the fastest way to refresh metadata and generate artefacts in one shot. The root invocation behaves exactly like `xtraq build --refresh-snapshot`.