CLI Reference

Treat this page like the sideline play sheet for nbadb. It is the fastest route from “what command do I need?” to “what exactly does that command accept?” without reading the CLI code directly.

Quick navigation

Opening possessions

Choose the command family first

Pipeline commands

These are the commands most operators touch first.

Run modes that matter most

Backfill commands

The backfill command group provides targeted extraction, gap detection, and journal management. Unlike the pipeline commands above, backfill operates selectively on specific seasons, endpoints, and parameter patterns.

Shared backfill options

nbadb backfill run

Use --dry-run to preview what would be extracted without executing:

nbadb backfill run --seasons 2023-24,2024-25 --endpoint box_score_traditional --dry-run

Use --force to re-extract entries already marked as done:

nbadb backfill run --seasons 2024-25 --force

Use --extract-only or --transform-only for partial pipeline runs. These flags are mutually exclusive.

nbadb backfill journal

The journal subcommand supports four actions via --action/-a:

Destructive actions require at least one filter (--endpoint, --seasons, or --status) and prompt for confirmation unless --yes/-y is passed.

Inspection and quality commands

nbadb status

Use --output-format json for scripts and CI. The JSON payload contains three top-level keys:

{
  "watermarks": [],
  "journal": {},
  "metadata": []
}

nbadb scan

The scan command replaces the deprecated run-quality with a broader quality and gap scanner:

nbadb scan --category data_quality,missing_table --severity warning --fail-on error

• --category/-c filters to specific check categories: cross_table, temporal, missing_table, data_quality
• --table/-t filters by table name prefix (e.g. fact_box_score, stg_, dim_)
• --severity/-s sets the minimum severity to display: error, warning, info
• --fail-on/-F exits non-zero when findings meet or exceed a severity threshold
• --report-path/-r writes the full JSON report to a file
• --output-format/-f switches between text (default) and json
• --ci enables GitHub Actions integration (step summary + annotations)

Distribution and artifact commands

nbadb extract-completeness

By default this writes coverage artifacts to artifacts/endpoint-coverage/:

• endpoint-coverage-matrix.json
• endpoint-coverage-summary.json
• endpoint-coverage-report.md

Pass --output-dir to change the destination.

Use --require-full in CI to fail when any of these source-coverage gaps remain non-zero:

• runtime_gap
• staging_only
• extractor_only
• source_only

Use --require-model-contract to fail when a staged stats surface still lacks an explicit downstream decision. The command summary prints separate counts for analytically modeled, passthrough-only, compatibility/reference-only, explicitly excluded, and still-unowned surfaces.

That endpoint-level contract is intentionally separate from the output-schema audit. The same summary now prints star schema coverage counts for transform outputs so you can see, independently, how many tables have a schema-backed final-tier contract versus how many still bypass star-schema validation.

nbadb endpoint-support-matrix

Use this when you need the strictest repo-local answer to "is every endpoint wired into the repo contract, and what kind of downstream ownership does it have?"

uv run nbadb endpoint-support-matrix --require-complete --require-season-type-contract

By default this writes companion artifacts next to extract-completeness under artifacts/endpoint-coverage/:

• endpoint-support-matrix.json
• endpoint-support-summary.json
• endpoint-support-report.md

It also refreshes the shared endpoint-coverage bundle in that directory, including the adequacy scorecard, so CI can gate the full contract from a single regeneration pass.

The command distinguishes three execution semantics:

• historical_backfill for stats/static surfaces that can be rebuilt from their earliest supported season or date
• reference_snapshot for reference/static snapshots
• live_snapshot for append-only live feeds such as scoreboard, odds, live play-by-play, and live box score packets

Use --require-complete to fail whenever any endpoint remains only partially wired into staging, transforms, or schemas. The summary also breaks downstream semantics into analytically modeled, passthrough-only, compatibility/reference-only, explicitly excluded, and unowned buckets so compatibility surfaces do not get mistaken for full analytical ownership. Use --require-season-type-contract to fail whenever a historical surface still lacks explicit season-type semantics or remains deliberately blocked from that contract.

nbadb endpoint-adequacy-scorecard

Use this when you want the endpoint-centric view that combines extraction coverage, support contract state, and downstream ownership into a single scorecard:

uv run nbadb endpoint-adequacy-scorecard

By default this writes companion artifacts next to extract-completeness under artifacts/endpoint-coverage/:

• endpoint-adequacy-scorecard.json
• endpoint-adequacy-scorecard-report.md

If you already regenerated endpoint-support-matrix or extract-completeness, those shared coverage runs also refresh this scorecard; use this command when you only need the adequacy pair itself.

The scorecard surfaces endpoint-level adequacy, downstream ownership, execution semantics, and the underlying coverage/support gap counts so you can quickly see whether each endpoint is analytically modeled, passthrough-only, compatibility/reference-only, explicitly excluded, or still unowned.

nbadb audit-models

Use this when you need the end-to-end model contract, not just endpoint completeness:

uv run nbadb audit-models --mode inventory --strictness consistency

The command writes model-audit artifacts under artifacts/model-audit/ by default:

• inventory.json
• matrix.json
• report.md
• result-table-inventory.json

probe, build, and full modes also emit:

• live-probes.json
• build-validation.json

When --baseline is provided, the command also writes baseline-comparison.json and enables no-regressions or zero-gaps enforcement. Pass --require-result-table-contract to fail when any runtime result table is still missing from staging, unowned downstream, or only weakly classified because schema coverage is incomplete.

Use the strictness levels progressively:

• consistency fails on discovery and audit-contract inconsistencies
• no-regressions compares the current inventory summary against a committed baseline, including new result-table contract failures
• zero-gaps requires both a baseline and zero remaining audit problems or result-table contract failures

The result-table inventory keeps warehouse ownership semantics explicit per runtime result set:

• modeled — analytically modeled with non-passthrough ownership
• passthrough_only — owned only by passthrough/union surfaces
• compatibility_reference_only — intentionally retained for compatibility/reference visibility
• excluded / deprecated — explicitly non-modeled but still visible
• unowned, weakly_classified, and missing — contract failures that should be fixed or explicitly classified

For CI canaries, keep --mode probe and use the repository’s configured canary profile so PRs exercise each source kind and parameter pattern without running the full live matrix.

nbadb docs-autogen

Use this when generated reference pages drift from code:

uv run nbadb docs-autogen --docs-root docs/content/docs

It regenerates:

• schema/{raw,staging,star}-reference.mdx
• data-dictionary/{raw,staging,star}.mdx
• diagrams/er-auto.mdx
• lineage/lineage-auto.mdx
• docs/lib/generated/{schema,lineage,schema-coverage}.json
• docs/lib/site-metrics.generated.ts

The same generator is also available via:

uv run python -m nbadb.docs_gen --docs-root docs/content/docs

The command prints updated: or unchanged: for each artifact, then a final summary line.

Shared behavior for pipeline commands

These notes apply to nbadb init, daily, and monthly.

• --data-dir overrides the default data directory (nbadb/) and the NBADB_DATA_DIR setting.
• --quality-check runs post-pipeline quality checks against the DuckDB file, but those checks are informational today: empty-table warnings are reported without failing the command.
• If stdout is an interactive terminal and --verbose is not set, the CLI uses the Textual TUI.
• Use --verbose to force plain log output and DEBUG-level logging.
• A single Ctrl+C attempts a graceful stop and preserves resume-safe journal/checkpoint state; pressing Ctrl+C again forces exit.
• Successful runs print a summary like this:

daily: 12 tables, 245,901 rows, 38.4s

Shared flags and defaults that matter most

Data and output defaults

• Default export formats come from NbaDbSettings.formats: sqlite, duckdb, csv, and parquet.
• nbadb init and nbadb export use all configured formats when you omit --format.
• nbadb download copies the Kaggle dataset into the target data directory and seeds nba.duckdb from nba.sqlite if only SQLite is present.
• nbadb upload ensures dataset-metadata.json exists before publishing.
• nbadb schema groups tables by output prefix. Analysis-ready convenience outputs use the analytics_* prefix.

Full command matrix

The matrix below mirrors the current Typer command signatures in src/nbadb/cli/commands.

Pipeline commands

Backfill commands

Inspection and quality commands

Distribution and artifact commands

Related guides

• Installation for setup and environment defaults
• Architecture for run-mode context and warehouse boundaries
• Daily Updates for recurring refreshes
• Kaggle Setup for download/upload workflows
• Troubleshooting Playbook for CI, docs, and artifact failures