Getting Started

Getting Started with Espresso

Requirements

• Python 3.10 or higher
• Linux, macOS, or Windows (via Windows Terminal or ConPTY)
• Zero external dependencies required!

---

Installation

Option 1: Via PyPI

pip install espressoTUI

Option 2: Universal Standalone Executable (Zero Installation)

Download the standalone espresso.pyz from GitHub Releases:

curl -LO https://github.com/kimusan/espresso/releases/latest/download/espresso.pyz
chmod +x espresso.pyz
./espresso.pyz gallery

Option 3: Pre-compiled Native Binaries (No Python Runtime Required)

Pre-compiled standalone binaries are available on every GitHub release:

• Linux x86_64: espresso-linux-x86_64
• macOS Apple Silicon: espresso-macos-arm64
• macOS Intel: espresso-macos-x86_64
• Windows x86_64: espresso-windows-x86_64.exe

---

Your First Application

Create a file named app.py:

from espresso import Model, Msg, Cmd, KeyMsg, Program, quit_app
from espresso.crema import Style, ROUNDED_BORDER

class CounterApp(Model):
    def __init__(self) -> None:
        self.count = 0

    def init(self) -> Cmd | None:
        return None

    def update(self, msg: Msg) -> tuple[Model, Cmd | None]:
        match msg:
            case KeyMsg(key="+" | "up" | "k"):
                self.count += 1
            case KeyMsg(key="-" | "down" | "j"):
                self.count -= 1
            case KeyMsg(key="q" | "esc"):
                return self, quit_app
        return self, None

    def view(self) -> str:
        box = (
            Style()
            .border(ROUNDED_BORDER)
            .border_foreground("#7D56F4")
            .padding(1, 3)
            .border_title(" Espresso Counter ")
        )
        body = f"Counter value: {self.count}\n\nPress [+] / [-] to count, [q] to quit."
        return box.render(body)

if __name__ == "__main__":
    Program(CounterApp(), alt_screen=True, mouse=True).run()

Run it:

python3 app.py

---

Built-in CLI Toolkit

Espresso includes the espresso command-line utility for exploring examples and scaffolding new applications:

# List all 14 interactive built-in example applications
espresso list

# Run any example by ID (e.g. 14 for Developer Workspace)
espresso run 14
espresso run 08

# Launch the interactive 39-component gallery
espresso gallery

# Scaffold a new TEA application with boilerplate ready to go
espresso new my_app.py

---

Next Steps

• Learn the architectural core in The Elm Architecture.
• Discover styling and layouts in Crema Styling Guide.
• Browse ready-to-use components in Beans Component Catalog.