CLI Reference¶

The dbp command is the default operational interface for DBPort. It covers project initialization, configuration, execution, publication, and status inspection.

Quick reference¶

Global options¶

--help                  Show command help
--version               Show CLI/package version
--verbose, -v           Increase output verbosity
--quiet, -q             Reduce output
--json                  Structured JSON output
--no-color              Disable Rich styling
--project PATH          Explicitly set project root
--model PATH            Explicitly set model directory
--lockfile PATH         Explicitly point to dbport.lock

Model resolution¶

When a command needs to resolve which model to operate on:

1. Positional MODEL argument — explicit model key (agency.dataset_id)
2. --model flag — explicit model directory relative to project root
3. CWD matching — current directory matched against model_root entries in the lock
4. default_model — persisted in dbport.lock (set via dbp config default model)
5. First model — fallback for single-model repos

Exit codes¶

In --json mode, errors include an error_type field for automation:

{
  "ok": false,
  "command": "model publish",
  "data": {
    "error": "No completed versions found in lock file. Specify --version explicitly.",
    "error_type": "runtime_error"
  }
}

Project setup¶

dbp init¶

Initialize a new model scaffold.

dbp init NAME [--template TEXT] [--dataset TEXT] [--agency TEXT] [--path PATH] [--force]

Creates a directory scaffold, registers the model in dbport.lock, and sets it as the default model.

dbp init regional_trends --agency wifor --dataset emp__regional_trends

See also: dbp status, dbp config default model

dbp status¶

Show resolved project and runtime state.

dbp status [--inputs] [--history] [--raw]

Shows project root, lockfile path, and for each model: agency, dataset ID, schema state, loaded inputs, and published versions.

dbp status check¶

Run health checks on the project.

dbp status check [--strict]

Verifies: lockfile exists and is valid TOML, DuckDB is available, credentials are set, and Python dependencies are installed.

Configuration¶

Manage project configuration via dbp config. Two sub-groups: default (repo-wide settings) and model (per-model settings).

Project defaults¶

dbp config default model [MODEL_KEY]¶

Show or set the default model for the project.

# Show current default
dbp config default model

# Set the default model
dbp config default model wifor.emp__regional_trends

dbp config default folder [FOLDER]¶

Show or set the models folder for new models created with dbp init.

# Show current folder
dbp config default folder

# Set the models folder
dbp config default folder examples

dbp config default hook [HOOK_PATH]¶

Show or set the run hook for the resolved model.

# Show current hook
dbp config default hook

# Set the run hook
dbp config default hook main.py

Model settings¶

dbp config model MODEL_KEY version [VERSION]¶

Show or set the configured publish version for a model.

# Show current version
dbp config model wifor.emp__regional_trends version

# Set the version
dbp config model wifor.emp__regional_trends version 2026-03-17

dbp config model MODEL_KEY schema [SOURCE]¶

Show or apply the output schema for a model.

# Show current schema
dbp config model wifor.emp__regional_trends schema

# Apply schema from SQL file
dbp config model wifor.emp__regional_trends schema sql/create_output.sql

See also: port.schema() (Python API equivalent)

dbp config model MODEL_KEY input [DATASET]¶

Show configured inputs or add one.

# Show configured inputs
dbp config model wifor.emp__regional_trends input

# Add an input
dbp config model wifor.emp__regional_trends input estat.nama_10r_3empers

# Add an input with filters and load immediately
dbp config model wifor.emp__regional_trends input estat.nama_10r_3empers \
    --filter wstatus=EMP --load

See also: port.load() (Python API equivalent)

dbp config model MODEL_KEY columns¶

Show all column metadata for a model.

dbp config model wifor.emp__regional_trends columns

dbp config model MODEL_KEY columns set COLUMN¶

Set codelist metadata for a column.

dbp config model wifor.emp__regional_trends columns set geo --id GEO --kind reference
dbp config model wifor.emp__regional_trends columns set year --type categorical

See also: port.columns.<name>.meta() (Python API equivalent)

dbp config model MODEL_KEY columns attach COLUMN TABLE¶

Attach a DuckDB table as the codelist source for a column.

dbp config model wifor.emp__regional_trends columns attach geo wifor.cl_nuts2024

See also: port.columns.<name>.attach() (Python API equivalent)

Model operations¶

dbp model sync [MODEL]¶

Sync a model from the catalog. Opens the model via DBPort and performs init-time sync (schema auto-detection, local state sync, last_fetched_at update).

dbp model sync
dbp model sync wifor.emp__regional_trends

dbp model load [MODEL]¶

Load configured inputs into DuckDB.

dbp model load
dbp model load --update    # resolve newest snapshots

See also: port.load() (Python API equivalent)

dbp model exec [MODEL]¶

Execute model transforms (the configured run hook or an explicit target).

dbp model exec
dbp model exec --target sql/transform.sql --timing

See also: port.execute() (Python API equivalent), Hooks & Execution (hook resolution and dispatch)

dbp model publish [MODEL]¶

Publish the output to the warehouse.

dbp model publish --version 2026-03-15
dbp model publish --dry-run
dbp model publish --refresh
dbp model publish --version 2026-03-15 --message "Initial release"

Version resolution (when --version is omitted): uses the latest completed version from the lock file. Does not fall back to the configured version field — use dbp model run for that.

See also: port.publish() (Python API equivalent)

dbp model run [MODEL]¶

Full lifecycle: sync, execute, and publish in one command.

dbp model run --version 2026-03-15 --timing
dbp model run wifor.emp__regional_trends --dry-run

Version resolution (when --version is omitted): first checks the configured version field in the lock (set via dbp config model … version), then falls back to the latest completed version.

See also: port.run() (Python API equivalent), Hooks & Execution (full execution model)

Output modes¶

All commands support --json for structured machine output:

{
  "ok": true,
  "command": "status",
  "data": {}
}

Default output uses Rich for readable tables, panels, and progress indicators.