Getting Started

This page gives you the shortest realistic path from install to a working Klix app.

If you want a more hands-on walkthrough, continue to Quickstart. If you want to understand the model first, read Architecture.

The Mental Model

Klix applications are built around a few core objects:

• App defines the application and owns the runtime
• Session represents one terminal instance
• Command objects define slash commands
• session.ui is where rendering and interactive widgets live

The default runtime loop is command-driven:

1. start the app
2. read a line of input
3. parse it as a slash command
4. run middleware
5. invoke the handler

That design is covered in App, Commands, and Router.

Smallest Useful App

Create main.py:

import klix

app = klix.App(
    name="mytool",
    version="0.1.0",
    description="A simple Klix app",
)

@app.on("start")
def on_start(session: klix.Session):
    session.ui.print("Ready.", color="accent", bold=True)

@app.command("/hello", help="Say hello")
def hello(session: klix.Session):
    session.ui.print("Hello from Klix.", color="success")

if __name__ == "__main__":
    app.run()

Run it:

python main.py

Then type:

/hello

What Happened

• App(...) created the command registry and runtime configuration
• @app.on("start") registered a lifecycle hook
• @app.command(...) created and registered a Command
• app.run() started the event loop and interactive session

See:

• App
• Events
• Commands

Using The Scaffold Instead

If you want a generated starting point instead of writing the app by hand:

klix init mytool
cd mytool
pip install -e .
mytool

The generated project includes:

• a working App
• a typed state class
• one event handler
• one middleware example
• one command with args_schema

See Building Your First CLI.

Where To Go Next

• Learn the runtime model in Architecture
• Learn command design in Adding Commands
• Learn UI rendering in Creating UI
• Learn persistence in Persistence