Metadata-Version: 2.3
Name: pieui
Version: 0.1.2
Summary: CLI client for PieUI.
Author: butusk0, DELTA37
Author-email: butusk0 <kirill.butusov@romanticai.com>, DELTA37 <gg_plastt@mail.ru>
Requires-Dist: jinja2>=3.1.0
Requires-Dist: adaptix>=3.0.0b12
Requires-Dist: dataclasses>=0.8
Requires-Dist: dataclasses-json>=0.6.7
Requires-Dist: fastapi>=0.136.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: openai-agents>=0.14.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: cent>=5.2.0
Requires-Dist: fastapi-socketio>=0.0.10
Requires-Dist: jsonpatch>=1.33
Requires-Dist: dataclasses-jsonschema>=2.16.0
Requires-Dist: aiohttp>=3.13.5
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# pie

Python CLI for Pie components.

The command surface follows the TypeScript `pieui` CLI:

```text
init
add
remove
list
push
pull
remote-remove
list-events
add-event
postbuild
```

Remote commands call the `pieui-storage` API:

```text
push
pull
remote-remove
```

## Setup

```bash
uv sync --python 3.14
cp .env.example .env
```

Do not pin the project to `3.14.0b1`: current `pydantic`/`pydantic-settings`
break on that beta. `uv sync --python 3.14` creates a managed CPython 3.14.0
environment.

## Config

The CLI reads `.env` with the `PIE_` prefix:

```text
PIE_API_BASE_URL=http://localhost:8000/api
PIE_USER_ID=default-user
PIE_PROJECT_SLUG=default-project
PIE_COMPONENTS_DIR=piecomponents
PIE_TIMEOUT_SECONDS=30
PIE_API_KEY=dev-master-key
```

`PIE_API_BASE_URL` must point to the API prefix of `pieui-storage`, for example:

```bash
PIE_API_BASE_URL=http://localhost:8000/api
```

`PIE_API_KEY` is sent to `pieui-storage` as the `x-api-key` header. The local
API default is `dev-master-key`.

## Commands

### init

Initialize the `piecomponents` directory:

```bash
uv run pie init
uv run pie init --out-dir packages/app
uv run pie init -o packages/app
```

### add

Create a local Python component project under `piecomponents/<ComponentName>`:

```bash
uv run pie add MyCustomCard
uv run pie add simple MySimpleCard
uv run pie add complex MyComplexCard
uv run pie add simple-container MySimpleContainerCard
uv run pie add complex-container MyContainerCard
```

If the type is omitted, `complex-container` is used, matching the TypeScript CLI.

The generated template is a minimal `piedemo` web project:

```text
piecomponents/MyCustomCard/
  pyproject.toml
  web.py
  pages/
    main.py
```

`web.py` registers `MainPage` on the root route: `{"": MainPage()}`.
`pages/main.py` also contains `MainCard`, where component events are declared.

### remove

Remove a local component directory:

```bash
uv run pie remove MyCustomCard
```

### list

List local components:

```bash
uv run pie list
uv run pie list simple
uv run pie list complex-container --src-dir app
uv run pie list complex-container -s app
```

Accepted filters:

```text
all
simple
complex
simple-container
complex-container
```

### push

Upload `piecomponents/<ComponentName>` to `pieui-storage`.

The storage API stores files under:

```text
PIE_USER_ID/PIE_PROJECT_SLUG/<ComponentName>/python/*
```

Command:

```bash
uv run pie push MyCustomCard
```

### pull

Download Python files from `pieui-storage` into `piecomponents/<ComponentName>`:

```bash
uv run pie pull MyCustomCard
```

### remote-remove

Delete the remote component from `pieui-storage`:

```bash
uv run pie remote-remove MyCustomCard
```

### list-events

List events declared by `MainCard.get_supported_events()`:

```bash
uv run pie list-events MyCustomCard
uv run pie list-events MyCustomCard --src-dir app
```

### add-event

Add a card event method and update `get_supported_events()`:

```bash
uv run pie add-event MyCustomCard alert
uv run pie add-event MyCustomCard alert --src-dir app
```

For `alert`, the command adds:

```python
def create_alert_event(self, data: dict | None = None):
    return self.create_event("alert", data or {})

def get_supported_events(self):
    return [
        "alert",
    ]
```

### postbuild

Generate a manifest file:

```bash
uv run pie postbuild
uv run pie postbuild --append --out-dir dist
uv run pie postbuild --src-dir src --out-dir public
```

## Project Layout

```text
pie/cli.py               CLI argument handling and command dispatch
pie/config.py            pydantic-settings config loaded from .env
pie/models.py            pydantic response models
pie/services/storage.py  pieui-storage API client
```
