pieui 0.1.5

CLI client for PieUI.

pie

Python CLI for Pie components.

The command surface follows the TypeScript pieui CLI:

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

Remote commands call the pieui-storage API:

push
pull
remote-remove

Setup

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:

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:

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:

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

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:

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:

uv run pie remove MyCustomCard

list

List local components:

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:

all
simple
complex
simple-container
complex-container

push

Upload piecomponents/<ComponentName> to pieui-storage.

The storage API stores files under:

PIE_USER_ID/PIE_PROJECT_SLUG/<ComponentName>/python/*

Command:

uv run pie push MyCustomCard

pull

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

uv run pie pull MyCustomCard

remote-remove

Delete the remote component from pieui-storage:

uv run pie remote-remove MyCustomCard

list-events

List events declared by MainCard.get_supported_events():

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():

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

For alert, the command adds:

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:

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

Project Layout

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