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

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 run-quality

• --report-path writes a machine-readable JSON report and creates parent directories as needed.
• The command exits non-zero when the database is missing, when no checks ran, or when the command errors.
• Current limitation: failed quality checks are reported, but they do not currently force a non-zero exit code once checks have executed. If CI must fail on bad results, parse the JSON report and gate on summary.failed > 0.

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 has neither downstream transform ownership nor an explicit exclusion decision. The command summary also prints model-ownership counts so you can distinguish owned, 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 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
• lineage/lineage.json

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, monthly, and full.

• --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

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