Metadata-Version: 2.4
Name: dlthub-start
Version: 0.8.0
Summary: Scaffold a new dltHub workspace.
Project-URL: Homepage, https://github.com/dlt-hub/dlthub-start
Project-URL: Repository, https://github.com/dlt-hub/dlthub-start
Project-URL: Issues, https://github.com/dlt-hub/dlthub-start/issues
Project-URL: Changelog, https://github.com/dlt-hub/dlthub-start/releases
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
Classifier: Development Status :: 4 - Beta
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 (beta)

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. Run it from inside an empty
project directory so the AI workbench files (skills + MCP server) land at the
**project root**, where your coding agent runs:

```bash
mkdir my-workspace && cd my-workspace
uvx dlthub-start@latest
```

No `uv`? Install the CLI with pip (into your current Python environment) and
run it directly:

```bash
pip install dlthub-start
dlthub-start
```

The CLI scaffolds the workspace, checks for `uv` (offering to install it if
missing), installs dependencies with `uv sync`, runs your first pipeline on
dltHub, then prompts for your coding agent and sets up its files. Finally it
launches that agent in the workspace, seeded with a starter prompt — or, if the
agent has no command-line launcher, prints the prompt and copies it to your
clipboard so you can paste it in.

The full setup runs through the interactive prompts:

```bash
mkdir my-workspace && cd my-workspace
uvx dlthub-start@latest
```

You can also pass a target directory (`uvx dlthub-start@latest my-workspace`),
but then the AI files live one level down — so launch your coding agent from
*inside* that directory. If the generated workspace needs `uv` and it is not
installed yet, the CLI offers to install it; or install it yourself via 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 your chosen coding agent (Claude, Cursor, or Codex).
- Shared dltHub AI toolkit files for data exploration, dltHub platform deployment, and REST API pipeline work.
- A local DuckDB-backed warehouse configuration for quick first runs.

## Usage

```bash
uvx dlthub-start@latest [project-dir] [options]
```

Initializes a workspace **in place** when the target is empty: the current
directory by default, or `project-dir` if given. A non-empty target never
fails — the CLI scaffolds into a free directory instead and tells you where it
landed. With no argument it nests a `playground` subdirectory (then
`playground-1`, `playground-2`, …); an explicit `project-dir` that's occupied
falls back to `<project-dir>-1`, `<project-dir>-2`, …. Existing contents are
left untouched. A directory holding only benign cruft — editor/OS files
(`.idea`, `.vscode`, `.DS_Store`), tool caches, and a bare `.git` — still counts
as empty and initializes in place; anything the scaffold ships (`.gitignore`,
`.dlt`, …) counts as content and triggers the fallback.

Common options:

| Option | Description |
| --- | --- |
| `--agent claude` | Use the Claude workbench files. Choose exactly one agent (`claude`, `cursor`, or `codex`); if omitted you're prompted (defaults to `claude`). |
| `--agent cursor` | Use the Cursor workbench files. |
| `--agent codex` | Use the Codex workbench files. |
| `--verbose`, `-v` | Stream output from underlying subprocesses. |

Examples:

```bash
uvx dlthub-start@latest                         # interactive setup in the current (empty) directory — recommended
uvx dlthub-start@latest --agent codex           # skip the agent prompt
uvx dlthub-start@latest my-workspace            # alternative: create + initialize a subdirectory
```

## Workspace contents

The bundled workspace is a quick, runnable first look: a sample online-shop
pipeline, local warehouse config, and a generated deployment module.

## Generated Workspace

The workspace is initialized at the project root, shaped roughly like this:

```text
.
|-- pyproject.toml
|-- pipeline.py
|-- __deployment__.py
|-- README.md
|-- .dlt/
|-- .mcp.json
`-- .claude/        # your selected agent (or .cursor/ / .codex/)
```

## Next Steps

From the workspace root:

```bash
uv run dlthub run load_sample_shop
uv run dlthub show
```

If you created the workspace with `--skip-uv-sync`, finish setup first with
`uv sync`. (If you scaffolded into a subdirectory, `cd` into it first.)

## Troubleshooting

`uvx: command not found`

Install the CLI with `pip install dlthub-start` (into your current Python
environment) and run `dlthub-start` instead. The CLI will still offer to
install `uv` before syncing the generated workspace dependencies.

`My workspace landed in a `playground`/`-1` subdirectory`

That's expected when the target wasn't empty: rather than refuse, the CLI
scaffolds into a free directory and prints where it went. To control the
location, pass an explicit empty target — `uvx dlthub-start@latest my-workspace`
— or run from an empty directory. The CLI never writes into a non-empty
directory; it picks a fresh one alongside it.

`uv sync` fails

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

```bash
uvx dlthub-start@latest my-workspace --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).

## Publishing

To build and publish a release to PyPI:

```bash
make publish
```

This removes any previous `dist/` artifacts, builds the package with
`uv build`, lists the artifacts, and prompts for a PyPI API token before
uploading with `uv publish`. Before publishing, run the release checklist in
[CONTRIBUTING.md](CONTRIBUTING.md) and make sure the version in
`pyproject.toml` has been bumped.
