dlthub-start 0.1.0

Scaffold a dltHub workspace from the official starter project.

dlthub-start

Create a ready-to-run dltHub workspace with example pipelines, local uv dependency setup, and bundled dltHub AI workbench files.

Quickstart

uvx is the recommended way to run the CLI:

uvx dlthub-start my-project

If uvx is not available yet, use pipx run instead:

pipx run dlthub-start my-project

The CLI prompts for a scaffold and AI workbench files, checks for uv, offers to install it if needed, offers to run uv sync, and prints next steps.

For a non-interactive setup with the recommended defaults:

uvx dlthub-start my-project --yes
cd my-project
uv run dlthub run load_breweries
uv run dlthub show

Both uvx and pipx run work. If the generated workspace needs uv and it is not installed yet, the CLI will offer to install it for you. If you prefer to install uv yourself, use the official uv installation guide.

What You Get

• A Python dltHub workspace with project metadata customized to your directory name.
• A bundled scaffold copied from this package, not downloaded at create time.
• dltHub AI workbench files for Claude, Cursor, and/or Codex.
• Shared dltHub AI toolkit files for data exploration, runtime deployment, REST API pipeline work, and transformations.
• A local DuckDB-backed warehouse configuration for quick first runs.

Usage

uvx dlthub-start <project-dir> [options]

Common options:

Option	Description
--yes, -y	Use the recommended path: starter scaffold, all AI workbenches, install uv if missing, and run uv sync.
--scaffold starter_workspace	Create the full starter workspace. This is the default recommended scaffold.
--scaffold minimal_workspace	Create a small workspace with one placeholder pipeline.
--agent claude	Include Claude workbench files. Pass --agent more than once to include multiple workbenches.
--agent cursor	Include Cursor workbench files.
--agent codex	Include Codex workbench files.
--skip-uv-sync	Create the scaffold and selected AI files, but stop before installing workspace dependencies.
--verbose, -v	Stream output from underlying subprocesses.

Examples:

uvx dlthub-start my-project --yes
uvx dlthub-start my-project --scaffold minimal_workspace
uvx dlthub-start my-project --agent claude --agent codex
uvx dlthub-start my-project --yes --skip-uv-sync

Scaffolds

Scaffold	Best For	Contents
starter_workspace	Exploring the full dltHub workflow quickly.	Open Brewery DB ingestion, Ibis transformations, scheduled data quality checks, marimo notebooks, and a generated deployment module.
minimal_workspace	Starting from a clean, small project.	One placeholder dlt pipeline, local warehouse config, and generated deployment module.

Generated Workspace

The starter scaffold creates a workspace shaped roughly like this:

my-project/
|-- pyproject.toml
|-- uv.lock
|-- starter_pipeline.py
|-- starter_transformations.py
|-- starter_data_quality.py
|-- __deployment__.py
|-- notebooks/
|-- .dlt/
|-- .agents/
|-- .claude/        # when Claude is selected
|-- .cursor/        # when Cursor is selected
`-- .codex/         # when Codex is selected

The minimal scaffold uses pipeline.py instead of the starter example modules.

Next Steps

For the starter scaffold:

cd my-project
uv run dlthub run load_breweries
uv run dlthub show

For the minimal scaffold:

cd my-project
uv run dlthub run load_data
uv run dlthub show

If you created the workspace with --skip-uv-sync, finish setup first:

cd my-project
uv sync

Troubleshooting

uvx: command not found

Use pipx run dlthub-start my-project instead. The CLI will still offer to install uv before syncing the generated workspace dependencies.

Target directory already exists and is not empty

Choose a new directory or empty the existing one. The CLI will not overwrite a non-empty workspace directory.

uv sync fails

Re-run with --verbose to see subprocess output:

uvx dlthub-start my-project --yes --verbose

If the scaffold was created successfully, you can also enter the workspace and run uv sync directly after fixing the underlying dependency or network issue.

Development

For local setup, tests, build commands, make workspace, and AI workbench scaffold regeneration, see CONTRIBUTING.md.