pieui 0.1.11

CLI client for PieUI.

pie

Python CLI and runtime helpers for PieUI applications.

The installed console script is pie and its entrypoint is pie.__main__:main. Commands are grouped by area:

pie web ...
pie card ...
pie page ...
pie create ...
pie login

Setup

uv sync --python 3.14

Run commands from this repository with:

uv run pie --help

The project requires Python >=3.14.

Configuration

The CLI loads .env through python-dotenv and reads these variables:

PIE_USER_ID=default-user
PIE_PROJECT=default-project
PIE_PROJECT_SLUG=default-project
PIE_COMPONENTS_DIR=pages/components
PIE_API_KEY=dev-master-key

Notes:

• PIE_COMPONENTS_DIR defaults to pages/components.
• PIE_PROJECT wins over PIE_PROJECT_SLUG; if both are absent, the current directory name is used.
• PIE_API_KEY is sent to pieui-storage as the x-api-key header.
• The storage API base URL is currently https://cdn-pieui.swarm.ing/api.

Create A Project

Create a new project, install pieui, write the starter files, and start a dev server on port 8008:

uv run pie create my-app

Generated layout:

my-app/
  web.py
  pages/
    main.py
    components/

The command runs:

uv init my-app
uv add pieui
uv run uvicorn web:app --port 8008

Web Commands

Load a Web object from module:attribute:

uv run pie web web:web

Verify that every page has a fields attribute:

uv run pie web web:web verify

Build static JSON from page fields into build.json:

uv run pie web web:web build

Card Commands

Add

Create a Python card file in PIE_COMPONENTS_DIR.

uv run pie card add simple MyCard
uv run pie card add complex MyCard
uv run pie card add container MyCard
uv run pie card add complex-container MyCard

Optional template modifiers:

uv run pie card add simple MyCard --io
uv run pie card add simple MyCard --ajax
uv run pie card add simple MyCard --io --ajax

Names are normalized to a Python class and snake-case filename. For example:

MyCard -> MyCard -> pages/components/my_card.py
trade widget -> TradeWidget -> pages/components/trade_widget_card.py

If the target file already exists, the command prints the existing path and does not overwrite it.

List

Scan PIE_COMPONENTS_DIR recursively for Python classes inheriting Card or InputCard:

uv run pie card list

The table includes inferred card type, Ajax support, IO support, and file path.

View

Print a plain-text report for one card:

uv run pie card view MyCard

The command reads the expected file from PIE_COMPONENTS_DIR, parses the class, and prints:

Name
File
Props
Ajax
IO
Events

List Events

Print events returned by get_supported_events():

uv run pie card list-events MyCard

If the card file or events are absent, the command prints No events found for MyCard.

Add Event

This command exists in the CLI, but Python source editing is not implemented:

uv run pie card add-event MyCard alert

It exits with:

[pie] Error: add-event requires TypeScript AST editing and is not implemented

Push

Upload one local Python card file to pieui-storage through the language batch API:

uv run pie card push MyCard

For MyCard, the CLI uploads:

pages/components/my_card.py

Remote key shape:

PIE_USER_ID/PIE_PROJECT/MyCard/python/my_card.py

The file request uses:

PUT /api/components/{user_id}/{project_slug}/{component_name}/batch/python

The command also uploads component capability metadata to eventSchema:

{
  "component": "MyCard",
  "input": false,
  "ajax": false,
  "io": false
}

Flags are inferred from the Python class:

• input: the class inherits InputCard.
• ajax: the class declares any of pathname, deps_names, or kwargs.
• io: the class declares any of use_socketio_support, use_centrifuge_support, use_mitt_support, or centrifuge_channel.

PIE_USER_ID is required for storage writes. PIE_PROJECT or PIE_PROJECT_SLUG selects the project.

Pull From Another User

Download Python files for a component owned by another user into PIE_COMPONENTS_DIR:

uv run pie card pull alice/MyCard

The project slug still comes from PIE_PROJECT, PIE_PROJECT_SLUG, or the current directory name.

Remote List

List remote components for a user/project:

uv run pie card remote list
uv run pie card remote list --user alice
uv run pie card remote list --user alice --project demo

Without flags, the command uses PIE_USER_ID and PIE_PROJECT / PIE_PROJECT_SLUG.

Remote Pull

Pull a component from the configured PIE_USER_ID and project:

uv run pie card remote pull MyCard

Downloaded Python files are written under PIE_COMPONENTS_DIR.

Page Commands

Add

Create a page module under the parent directory of PIE_COMPONENTS_DIR and register it in web.py:

uv run pie page add dashboard
uv run pie page add admin/users

With the default PIE_COMPONENTS_DIR=pages/components, page files are written to pages/.

Examples:

dashboard -> pages/dashboard.py -> route "dashboard"
admin/users -> pages/admin_users.py -> route "admin/users"

web.py must exist next to the pages/ directory and contain a web = Web({...}) assignment with a literal pages dictionary.

View

Import a page module and print page details:

uv run pie page view dashboard

The report includes:

Page
Module
Path
is_typed
Form process
Ajax

Login

Start the browser login flow:

uv run pie login

The command:

1. Generates a one-time code.
2. Opens https://pieui.swarm.ing/connect?code=....
3. Polls https://api-pieui.swarm.ing/api/external/credentials.
4. Saves the returned config to .pie/config.json.
5. Appends PIE_USER_ID, PIE_PROJECT, and PIE_API_KEY to .env.

The returned config must contain these keys:

user_id
project
api_key

Current Command Reference

pie --help
pie web MODULE:ATTR [verify|build]
pie card add {simple,complex,container,complex-container} NAME [--io] [--ajax]
pie card list
pie card push NAME
pie card pull USER/COMPONENT
pie card view NAME
pie card list-events NAME
pie card add-event NAME EVENT_NAME
pie card remote list [--user USER_ID] [--project SLUG]
pie card remote pull NAME
pie page add NAME
pie page view NAME
pie create NAME
pie login

Code Layout

pie/__main__.py                 CLI argument parsing and dispatch
pie/config.py                   environment-backed settings
pie/code/card_add.py            card template generation
pie/code/card_list.py           local card discovery
pie/code/card_inspect.py        card view and event inspection
pie/code/card_push.py           single-card upload command
pie/code/card_pull.py           USER/COMPONENT pull command
pie/code/card_remote.py         configured remote list/pull commands
pie/code/page_create.py         page generation, web.py registration, page view
pie/code/create.py              project scaffolding
pie/code/login.py               PieUI login flow
pie/code/web.py                 Web loader and verifier
pie/code/build.py               build.json generation
pie/code/services/storage.py    pieui-storage API client
pie/code/services/models.py     storage response models