Metadata-Version: 2.4
Name: dlthub-start
Version: 0.1.0
Summary: Scaffold a dltHub workspace from the official starter project.
Author: dltHub
License: dltHub License
        
        Copyright 2026 ScaleVector, GmbH. All rights reserved.
        
        
        ## Definitions
        
        "Agreement" means the agreement between ScaleVector, GmbH and its affiliates
        (collectively, "dltHub") and you governing the use of dltHub Services, including
        dltHub Platform, as those terms are defined in the applicable dltHub Terms of Use
        available at: https://dlthub.com/terms.
        
        "dltHub Services" means dltHub Platform and any other products or services offered
        by dltHub, as defined in the Agreement.
        
        "Derivative Works" means any work that is based on, incorporates, or is derived
        from the Licensed Materials, including but not limited to code generated with the
        assistance of the Licensed Materials, modified copies, adaptations, and projects
        into which the Licensed Materials is installed or integrated.
        
        "Licensed Materials" means the source code, object code, data, and/or other works,
        including educational materials, to which this license applies.
        
        ## Scope of Use
        
        You may view, use, copy, modify, publish, and distribute the Licensed Materials
        solely in connection with dltHub Services under a governing Agreement. Any use of
        the Licensed Materials outside of dltHub Services is not permitted under this
        license.
        
        Without limiting the foregoing, the following are examples of permitted use:
        
        1. Using toolkits and skills provided by dltHub to develop, build, test,
           and deploy data pipelines on dltHub Platform.
        2. Copying and modifying toolkit code for use exclusively with dltHub Services and on
           dltHub Services.
        3. Using the Licensed Materials to generate code intended for deployment on dltHub
           Platform.
        
        The following are examples of uses that are NOT permitted under this license:
        
        1. Using toolkits and skills provided by dltHub to generate code or pipelines for 
           deployment on a third-party runtime platform or orchestration service that is not
           part of dltHub Services.
        2. Modifying toolkits to replace, bypass, or substitute components that are part of
           dltHub services in order to operate within a third-party development environment.
        3. Incorporating the Licensed Materials or Derivative Works into any product or
           service that competes with the Licensed Materials, or any other dltHub Services.
        4. Providing the Licensed Materials to third parties as part of a hosted or managed
           service that replicates the functionality of dltHub Services.
        
        Use beyond the scope of this license requires a separate license agreement
        negotiated with dltHub on a case-by-case basis.
        
        
        ## Redistribution
        
        Redistribution of the Licensed Materials, with or without modification, is
        permitted provided that this license notice is included in all copies or substantial
        portions of the Licensed Materials. All recipients are bound by the same scope of
        use restrictions set forth in this license.
        
        ## Intellectual Property
        
        dltHub retains all right, title, and interest in and to the Licensed Materials as
        originally published.
        
        dltHub waives all intellectual property claims over Derivative Works, provided that:
        
        1. The use of the Licensed Materials complies with the scope of use set forth in
           this license, and
        2. This license notice is retained in all copies or substantial portions of the
           Licensed Materials contained within the Derivative Works.
        
        This waiver extends to the Licensed Materials itself as incorporated into Derivative
        Works — you are free to use, modify, and distribute it within your Derivative Works
        without further restriction, subject only to the scope of use and redistribution
        terms above.
        
        
        ## Disclaimer and Limitation of Liability
        
        THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITH ALL FAULTS. DLTHUB AND ITS
        LICENSORS DISCLAIM ALL WARRANTIES, WHETHER EXPRESS, IMPLIED, STATUTORY, OR
        OTHERWISE, INCLUDING WITHOUT LIMITATION THE WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT. DLTHUB AND ITS LICENSORS'
        TOTAL AGGREGATE LIABILITY RELATING TO OR ARISING OUT OF YOUR USE OF OR DLTHUB'S
        PROVISIONING OF THE LICENSED MATERIALS SHALL BE LIMITED TO ONE THOUSAND DOLLARS
        ($1,000). IN NO EVENT SHALL DLTHUB OR ITS LICENSORS BE LIABLE FOR ANY LOST PROFITS,
        LOSS OF REVENUE, LOST BUSINESS, COSTS OF COVER OR ANY INCIDENTAL, SPECIAL,
        EXEMPLARY OR PUNITIVE DAMAGES OF ANY KIND OR NATURE IN CONNECTION WITH THIS LICENSE
        OR THE LICENSED MATERIALS.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beaupy>=3.9
Requires-Dist: rich>=13.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```bash
uvx dlthub-start my-project
```

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

```bash
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:

```bash
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](https://docs.astral.sh/uv/getting-started/installation/).

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

```bash
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:

```bash
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:

```text
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:

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

For the minimal scaffold:

```bash
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:

```bash
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:

```bash
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](CONTRIBUTING.md).
