Commands

snapshot

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

Usage

xtraq snapshot [options]

Configuration

.xtraqconfig must exist in the project root. When it is missing or invalid the CLI prompts to run xtraq init and, if approved, bootstraps the file before retrying.
XTRAQ_PROJECT_PATH pins the CLI to a specific project root when the current working directory differs (solution-level builds, CI pipelines, or dotnet xtraq invocations). Passing -p/--project-path updates the environment variable for the current process automatically.
XTRAQ_GENERATOR_DB must be supplied via environment variables or .env. The command fails fast (and preserves .xtraqconfig) when no connection string is available.
Optional allow-list filters come from .xtraqconfig (BuildSchemas). Use --procedure for temporary per-run scoping instead of editing the tracked config.
--procedure never touches .env and remains active only for the current invocation.

If the connection string is missing or empty, the command fails fast with guidance to update .env.

Options

Option	Description
`-p, --project-path <project-path>`	Point to a different project root that already contains `.env`.
`--no-cache`	Ignore existing `.xtraq/cache` entries and force a full re-parse.
`--procedure <schema.proc>`	Comma-separated filter applied only for the current invocation (no `.env` or config edits).
`-v, --verbose`	Emit per-procedure progress, timings, and cache reuse hints.
`--telemetry`	Persist a JSON telemetry report for the run under `.xtraq/telemetry`.
`--ci`	Switch to CI-friendly output (plain progress, no ANSI art).

The remaining global switches (such as --debug, --telemetry, and --ci) behave exactly as described in the CLI overview.

When --no-cache is specified you will only see [proc-loaded] entries (no [proc-skip]) and the banner [cache] Disabled (--no-cache). Use this after modifying parsing/JSON heuristics or when validating metadata changes.

Behavior Contract

Aspect	Details
Invocation	`xtraq snapshot` with optional project path.
Reads	`.xtraqconfig`, `.env` (when present), existing `.xtraq/cache` entries, stored procedure metadata from SQL Server.
Writes	`.xtraq/snapshots/*/.json`, `.xtraq/cache/*.json`, optional telemetry files under `.xtraq/telemetry`.
Exit codes	`0` success; non-zero indicates configuration/validation failure (missing config or connection) or database extraction errors.
Preconditions	Accessible `.xtraqconfig` and database connection string; optional schema/procedure filters respected from config and overrides.
Side effects	May bootstrap `.xtraqconfig` via `xtraq init` when permitted; schedules a background update check unless disabled; outside CI it prompts to install the update when available; can emit telemetry summaries.

Examples

# Standard metadata refresh using the current directory
xtraq snapshot

# Force fresh parsing while diagnosing snapshot issues
xtraq snapshot --no-cache --verbose

# Run against the debug sandbox and inspect only the identity schema procedures
xtraq snapshot -p debug --procedure identity.%

Edit this pageorReport an issue

init

Initialize a xtraq project with a tracked `.xtraqconfig` snapshot and minimal `.env` secrets. Bootstraps a `.env` file (or updates an existing one) with the generator connection string and logging toggles only, and writes a tracked `.xtraqconfig` snapshot for every non-sensitive default.

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.