painted — Quickstart
Description: painted documentation

# Quickstart

Five copy/paste steps: install → first `Block` → first composition → first `print_block` → first `run_cli`.

## 1) Install

    pip install painted

## 2) First `Block`

Create a `Block` (an immutable rectangle of styled cells):

    from painted import Block, Style

    block = Block.text("deploy OK", Style(fg="green", bold=True))

## 3) First composition

Compose blocks into a small “card” using functions like `join_vertical` and `border`:

    from painted import Block, Style, border, join_vertical, ROUNDED

    header = Block.text(" api-gateway ", Style(bold=True, reverse=True))
    status = join_vertical(
        Block.text("  replicas: 2/3 ready", Style(fg="yellow")),
        Block.text("  /health:  200  12ms", Style(fg="green")),
    )
    card = border(join_vertical(header, status), chars=ROUNDED)

## 4) First `print_block`

Print a `Block` to stdout. When stdout is a TTY, painted emits ANSI styles; when piped, it emits plain text.

    from painted import print_block

    print_block(card)

## 5) First `run_cli`

Use `run_cli()` when you want one entrypoint that can produce quiet/verbose output, JSON, and/or an interactive TUI.

    import sys
    from painted import Block, CliContext, run_cli

    def render(ctx: CliContext, data: dict) -> Block:
        return Block.text(f"status: {data['status']}")

    def fetch() -> dict:
        return {"status": "ok"}

    if __name__ == "__main__":
        run_cli(sys.argv[1:], render=render, fetch=fetch)

Run it:

    python myapp.py
    python myapp.py --json
    python myapp.py -q
    python myapp.py -v
    python myapp.py -i