CLI Reference
ixtract ships with 9 commands. All commands connect to PostgreSQL by default; use --source-type for MySQL or SQL Server.
Common connection flags
Section titled “Common connection flags”All commands that connect to a source accept:
| Flag | Description | Default |
|---|---|---|
--database | Database name | — |
--user | Username | — |
--password | Password | — |
--host | Hostname | localhost |
--port | Port | 5432 |
--source-type | postgresql | mysql | sqlserver | postgresql |
profile
Section titled “profile”Profile a table: row count, PK distribution, source latency, skew.
ixtract profile <table> --database <db> --user <user> --password <pw>Output includes:
- Estimated row count
- PK column and type
- Source latency (p50)
- Coefficient of variation (CV) — flags skew if CV > 1.0
Plan an extraction without executing it.
ixtract plan <table> --database <db> --user <user> [--standard] [context flags] [cost flags]| Flag | Description |
|---|---|
--standard | Full output: worker resolution, chunk boundaries, advisories, verdict |
Context flags (see Runtime Context):
| Flag | Values |
|---|---|
--source-load | low | normal | high |
--network-quality | good | normal | degraded |
--priority | low | normal | high |
--max-workers | Integer hard cap |
--min-workers | Integer floor |
--target-duration-seconds | Advisory |
--maintenance-window-minutes | Advisory |
--disk-budget-gb | Advisory |
--egress-budget-gb | Advisory |
--context-file | Path to JSON file with all context fields |
--force | Override NOT RECOMMENDED verdict |
Cost flags (see Cost Model):
| Flag | Description |
|---|---|
--compute-rate | Cost per worker-second (decimal) |
--egress-rate | Cost per GB egressed (decimal) |
--connection-rate | Cost per connection-second (decimal) |
--cost-file | Path to JSON file with rates |
execute
Section titled “execute”Profile, plan, and extract in one step.
ixtract execute <table> --database <db> --user <user> \ [--output <dir>] [--output-format <fmt>] [context flags] [cost flags] [--force]| Flag | Description | Default |
|---|---|---|
--output | Output directory | ./output |
--output-format | parquet | csv | s3 | gcs | parquet |
On completion, writes _manifest.json to the output directory.
explain
Section titled “explain”Show the full reasoning for the last plan: worker source, context applied, chunks.
ixtract explain --object <table> --database <db> --user <user> [--standard]diagnose
Section titled “diagnose”Classify recent throughput deviation and surface anomalies.
ixtract diagnose --object <table>Output includes:
- Direction-aware deviation (degrading / improving / stable)
- Anomaly detection result (σ deviation from baseline)
- Recommended action (if any)
history
Section titled “history”Show all past runs for a table.
ixtract history <table>Columns: run ID, date, workers, throughput (rows/sec), duration, diagnosis result.
metrics
Section titled “metrics”Show aggregate performance metrics for a table.
ixtract metrics --object <table>Includes: best run, worst run, mean throughput, p95 duration, controller convergence status.
replay
Section titled “replay”Re-execute a historical run using its stored plan exactly.
ixtract replay --run-id <id> [--force] [--output-dir <dir>]| Flag | Description |
|---|---|
--run-id | Run ID from ixtract history |
--force | Skip version mismatch warning |
--output-dir | Output directory (defaults to original) |
Output shows Decision Check (original vs. replay side-by-side), Outcome Delta (throughput, duration), and Determinism verification.
Replay guarantees identical decisions, not identical results. Timing and external system state may differ.
benchmark
Section titled “benchmark”Calibrate throughput at multiple worker counts to eliminate cold-start bias.
ixtract benchmark <table> --database <db> --user <user>Runs extraction at 1, 2, 4, 8 workers (or configured range) and stores calibration data. The planner uses this data instead of a single-run estimate.