This blog will combine practical tutorials, design notes, comparisons, and reflections on where command-line applications remain useful. The goal is to make CLI development easier to understand and more enjoyable to explore.

Im ersten Artikel der Reihe Erste Schritte mit quiCkLI wirst du ein Begrüßungstool mit genau drei Konzepten erstellen: Application, Argument und Option.

Was du bauen wirst​

$ python hello.py Ada
$ Hello, Ada!

$ python hello.py Ada --uppercase
$ HELLO, ADA!

Eine einzige Datei. Keine Konfiguration. Unter dreißig Zeilen Python.

Voraussetzungen​

Installiere quickli in einer virtuellen Umgebung:

$ python -m venv .venv
$ source .venv/bin/activate   # Windows: .venv\Scripts\activate
$ pip install quickli

Du benötigst Python 3.12 oder neuer.

Schritt 1: Die Anwendung erstellen​

from quickli import Application

app = Application(
    name="hello",
    description="Grüße eine Person von der Kommandozeile.",
)

Application ist der Wurzel-Container. Er verwaltet Registrierung und Dispatch. Du gibst ihm einen Namen (für die Hilfsausgabe) und eine kurze Beschreibung.

Schritt 2: Einen Handler registrieren​

from quickli import Application, Argument, Option

@app.entrypoint(
    help_text="Einen Gruß ausgeben.",
    arguments=[Argument("name", help_text="Name, der gegrüßt werden soll.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Den Gruß in Großbuchstaben ausgeben.",
        ),
    ],
)
def greet(name: str, uppercase: bool = False) -> str:
    message = f"Hello, {name}!"
    return message.upper() if uppercase else message

@app.entrypoint registriert eine Funktion als einzelnen Handler für diese Anwendung.

• Argument("name") deklariert einen erforderlichen Positionswert.
• Option("uppercase", is_flag=True) deklariert einen booleschen Schalter.

Schritt 3: Die Anwendung ausführen​

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

Application.run() liest standardmäßig sys.argv[1:] und gibt das Handler-Ergebnis zurück. Du entscheidest, was damit zu tun ist.

Die vollständige Datei​

from __future__ import annotations

from quickli import Application, Argument, Option


app = Application(
    name="hello",
    description="Grüße eine Person von der Kommandozeile.",
)


@app.entrypoint(
    help_text="Einen Gruß ausgeben.",
    arguments=[Argument("name", help_text="Name, der gegrüßt werden soll.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Den Gruß in Großbuchstaben ausgeben.",
        ),
    ],
)
def greet(name: str, uppercase: bool = False) -> str:
    message = f"Hello, {name}!"
    return message.upper() if uppercase else message


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

Probiere es aus​

$ python hello.py Ada           # Hello, Ada!
$ python hello.py Ada -u        # HELLO, ADA!
$ python hello.py               # (Hilfsausgabe)

Was du gelernt hast​

• Application verwaltet Registrierung und Dispatch.
• @app.entrypoint registriert einen einzelnen Handler für die gesamte Anwendung.
• Argument beschreibt positionalen, erforderlichen Input.
• Option mit is_flag=True fügt einen booleschen Schalter hinzu.
• Application.run(argv) gibt das Ergebnis zurück - du steuerst die Ausgabe.

Weiter in dieser Reihe​

Der nächste Artikel fügt Datei-Input, Validierung und globale Optionen hinzu, indem er einen kleinen Datei-Viewer nach dem Vorbild des Unix-cat-Befehls baut.

📖 Teil 2: Dateien lesen - das quickcat-Tool →

Dieser Beitrag beantwortet diese Frage ehrlich. Er ist der erste einer Reihe über die Entwicklung von quiCkLI - was es ist, warum es existiert und wohin es geht.

Die Lücke, die ich füllen wollte​

Ich wollte ein Framework, auf das ich einen Lernenden zeigen und sagen könnte: Alle wichtigen Teile sind hier sichtbar. Wenn ich versuchte, mit einem bestehenden Framework zu erklären, wie eine CLI-Anwendung funktioniert, stieß ich immer wieder auf dasselbe Problem. Das Framework war gut darin, Komplexität zu verbergen - was für Produktionscode großartig ist - aber genau dieses Verbergen machte es schwer zu verstehen, was tatsächlich passiert.

Ich wollte keines dieser Tools ersetzen. Ich wollte etwas bauen, das als Referenzimplementierung dienen kann - ein Framework, das klein genug ist, dass ein Entwickler den gesamten Quellcode an einem Nachmittag lesen und verstehen kann, wie ein CLI aus ersten Prinzipien zusammengesetzt wird.

Was „minimal" hier bedeutet​

quickli ist nicht minimal, weil es weniger Funktionen hat. Es ist minimal in dem Sinn, dass jeder Teil des Designs bewusst und sichtbar ist.

• Der Anwendungs-Container verwaltet Registrierung und Dispatch. Diese Grenze ist explizit.
• Argumente sind positional und geordnet. Optionen sind benannt. Das sind verschiedene Dinge.
• Konvertierung und Validierung sind separate Schritte, die vor dem Handler stattfinden.
• Das Framework gibt Ergebnisse an den Aufrufer zurück. Es liest sys.argv[1:] standardmäßig, druckt aber keine Ausgabe und behandelt keine Exit-Codes.

Jede dieser Entscheidungen wurde getroffen, weil sie die Mechanik einer CLI für jemanden sichtbar lässt, der lernt, wie sie funktioniert.

Die leitende Frage​

Für jede Funktion, die ich in quickli hinzuzufügen überlegte, stellte ich dieselbe Frage: Macht das das Framework einfacher, davon zu lernen, oder macht es es mächtiger auf Kosten des Verständnisses?

Diese Frage hat quickli klein gehalten.

Was als Nächstes kommt​

Der nächste Beitrag in dieser Reihe befasst sich damit, für wen quiCkLI gedacht ist - die Zielgruppe und was ich hoffe, dass sie aus der Verwendung mitnehmen.

📖 Teil 2: Für wen ist quiCkLI? →

quiCkLI makes these decisions explicit: applications own dispatch, commands describe operations, and arguments and options describe inputs. That simplicity is useful, but it also means the caller still owns process output and exit codes.

Das Beispiel ist quickcat, ein minimaler Datei-Viewer nach dem Vorbild des Unix-cat-Befehls.

Was du bauen wirst​

$ python quickcat.py README.md
$ python quickcat.py README.md --number
$ python quickcat.py README.md -i CONTRIBUTING.md --verbose

Neue Konzepte​

Globale Optionen​

app = Application(
    name="quickcat",
    description="Ein winziges cat-ähnliches CLI, gebaut mit quickli.",
    global_options=[
        Option("verbose", short_name="v", is_flag=True, help_text="Ausführliche Ausgabe aktivieren."),
    ],
)

Globale Optionen werden auf Application-Ebene definiert. Jeder Handler, der sie verwenden möchte, muss den entsprechenden Parameter deklarieren.

Der file_path-Validator​

Argument("path", help_text="Primärer Dateipfad.", validators=[file_path()]),
```bash

$ `file_path()` ist eine eingebaute Validator-Factory. Sie gibt ein Callable zurück, das
$ quickli nach dem Parsen, aber vor dem Aufruf deines Handlers ausführt. Wenn der Pfad
$ nicht existiert oder keine Datei ist, wird die Ausführung mit einer klaren Fehlermeldung
$ abgebrochen.

$ ## Wiederholbare Optionen

$ ```python
$ Option(
$     "include",
$     short_name="i",
$     multiple=True,
$     validators=[file_path()],
$     help_text="Zusätzliche Dateipfade, die nach der primären Datei ausgegeben werden.",
$ ),

multiple=True ermöglicht es, die Option mehrfach zu übergeben. Der Handler empfängt include als list[Path] | None.

Das vollständige Beispiel​

from __future__ import annotations

from pathlib import Path

from quickli import Application, Argument, Option, file_path


app = Application(
    name="quickcat",
    description="Ein winziges cat-ähnliches CLI, gebaut mit quickli.",
    global_options=[
        Option("verbose", short_name="v", is_flag=True, help_text="Ausführliche Ausgabe aktivieren."),
    ],
)


@app.entrypoint(
    help_text="Eine oder mehrere Textdateien auf stdout ausgeben.",
    arguments=[
        Argument("path", help_text="Primärer Dateipfad.", validators=[file_path()]),
    ],
    options=[
        Option("encoding", short_name="e", default="utf-8", help_text="Zeichenkodierung."),
        Option("number", short_name="n", help_text="Zeilennummern ausgeben.", is_flag=True),
        Option(
            "include",
            short_name="i",
            multiple=True,
            validators=[file_path()],
            help_text="Zusätzliche Dateipfade nach der primären Datei.",
        ),
    ],
)
def show(
    path: Path,
    encoding: str = "utf-8",
    number: bool = False,
    include: list[Path] | None = None,
    verbose: bool = False,
) -> str:
    input_paths = [path, *(include or [])]
    rendered_chunks: list[str] = []

    for input_path in input_paths:
        text = input_path.read_text(encoding=encoding)
        lines = text.splitlines()

        if number:
            lines = [f"{index:>4}  {line}" for index, line in enumerate(lines, start=1)]

        if verbose:
            rendered_chunks.append(f"==> {input_path} <==")
        rendered_chunks.append("\n".join(lines))

    return "\n".join(chunk for chunk in rendered_chunks if chunk)


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

Was du gelernt hast​

• global_options auf Application deklarieren Optionen, die für jeden Handler verfügbar sind.
• file_path() validiert, dass ein Wert auf eine vorhandene, lesbare Datei zeigt.
• multiple=True sammelt wiederholte Optionswerte in einer Liste.
• Validatoren laufen vor dem Handler und halten dessen Körper sauber.

Weiter in dieser Reihe​

Der abschließende Artikel baut eine kubectl-ähnliche Multi-Command-Anwendung mit @app.command, eigenen Validator-Factories und CommandExecutionError.

📖 Teil 3: Multi-Command-Anwendungen →

Die primäre Zielgruppe​

quiCkLI ist für Entwickler, die verstehen wollen, wie eine Kommandozeilenanwendung zusammengesetzt wird - nicht nur, wie man eine verwendet.

Diese Gruppe umfasst:

• Studierende und Berufsanfänger, die ihre ersten Kommandozeilentools bauen. Sie brauchen ein Framework, bei dem die Mechanik sichtbar ist, nicht hinter einer polierten Abstraktion verborgen.
• Entwickler, die aus anderen Sprachen kommen und den Python-Ansatz zum CLI-Design verstehen wollen, ohne den Quellcode eines großen Frameworks lesen zu müssen.
• Erfahrene Entwickler, die eine kleine, lesbare Referenzimplementierung als Lehrmittel oder Ausgangspunkt für eigene Experimente nutzen möchten.

Für wen quiCkLI nicht geeignet ist​

Wenn du ein produktives CLI-Tool baust und Shell-Vervollständigung, verschachtelte Unterbefehle, Konfigurationsdateien und einen umfangreichen Hilfe-Renderer benötigst, verwende click oder typer. Sie sind ausgezeichnete Tools, die genau für diesen Zweck entwickelt wurden.

quiCkLI trifft bewusste Kompromisse, die in einem produktiven Framework inakzeptabel wären:

• Es liest sys.argv[1:] standardmäßig, aber lässt sich mit auto_sys_argv=False deaktivieren.
• Es druckt keine Ausgabe und wählt keine Exit-Codes.
• Es bietet keine Shell-Vervollständigung.
• Die Plugin-Erkennung ist manuell.

Das sind keine Versehen. Es sind bewusste Entscheidungen, die die Teile sichtbar halten.

Was die Zielgruppe braucht​

Ein Lernender braucht:

1. Eine kleine Oberfläche. Wenn das Framework zwanzig Klassen hat, erfordert das Verständnis, alle zwanzig zu kennen. quickli hat fünf Kernkonzepte.
2. Explizite Grenzen. Wo endet das Framework und wo beginnt die Anwendung? In quickli ist diese Grenze Application.run(). Die Verantwortung für Exit-Codes und Ausgabe bleibt bei der Anwendung.
3. Ausführbare Beispiele. Theorie reicht nicht. Die Referenzbeispiele im Repository sind echte, ausführbare Tools.

Was das für das Projekt bedeutet​

quiCkLI für Lernende nützlich zu halten bedeutet, dem natürlichen Impuls zu widerstehen, Funktionen hinzuzufügen. Jede Funktion vergrößert die Oberfläche. Jede Abstraktion verbirgt etwas.

Der Qualitätsmaßstab des Projekts ist nicht nur funktioniert es - sondern ist es noch einfach zu verstehen.

Was du bauen wirst​

$ python app.py get pods
$ python app.py get pods --output json --namespace ops
$ python app.py describe pod api-7d4f5f6b89-l2xq9
$ python app.py logs api-7d4f5f6b89-l2xq9 --tail 5 --timestamps
$ python app.py apply manifests/web-pod.yaml --dry-run

@app.command vs. @app.entrypoint​

Bisher hast du @app.entrypoint verwendet, das einen einzelnen Handler für die gesamte Anwendung registriert. Für mehrere Befehle verwendest du stattdessen @app.command:

@app.command(
    name="get",
    help_text="Ressourcen im ausgewählten Namespace auflisten.",
    arguments=[...],
    options=[...],
)
def get(resource: str, ...) -> str:
    ...

Der name-Parameter wird zum ersten Token in der Kommandozeile. Wenn name weggelassen wird, wird der Funktionsname verwendet. Du kannst so viele Befehle registrieren, wie du benötigst.

Eigene Validator-Factories​

quickli enthält eingebaute Validatoren (file_path, positive_number und weitere), aber du kannst eigene nach demselben Muster schreiben:

def one_of(*choices: str):
    allowed = tuple(choices)
    description = "eines von: " + ", ".join(allowed)

    def validate(value: object) -> object:
        if value not in allowed:
            raise ValueError(f"Erwartet eines von: {', '.join(allowed)}")
        return value

    validate.description = description
    return validate

Eine Validator-Factory gibt ein Callable zurück, das:

1. Den konvertierten Wert empfängt.
2. Den Wert unverändert zurückgibt, wenn er gültig ist.
3. ValueError mit einer klaren Nachricht auslöst, wenn nicht.

CommandExecutionError​

CommandExecutionError ist für erwartete, domänenspezifische Fehler:

def _find_pod(name: str, namespace: str) -> Pod:
    for pod in PODS:
        if pod.namespace == namespace and pod.name == name:
            return pod
    raise CommandExecutionError(
        f"Pod '{name}' wurde im Namespace '{namespace}' nicht gefunden."
    )

Diese Ausnahme propagiert unverändert aus Application.run(). Deine Anwendung kann sie abfangen und in einen Exit-Code umwandeln.

Globale Optionen, die alle Befehle teilen​

Deklariere Optionen einmalig auf Application. Jeder Handler, der sie benötigt, deklariert denselben Parameternamen:

app = Application(
    name="pyk5l",
    global_options=[
        Option("namespace", short_name="n", default="default"),
        Option("output", short_name="o", default="table",
               validators=[one_of("table", "json", "wide")]),
        Option("verbose", short_name="v", is_flag=True),
    ],
)

Was du gelernt hast​

• @app.command registriert benannte Befehle in einer Multi-Command-Anwendung.
• Eigene Validator-Factories folgen demselben Muster wie eingebaute Validatoren.
• CommandExecutionError signalisiert erwartete domänenspezifische Fehler.
• Auf Application deklarierte globale Optionen sind für jeden Handler verfügbar.

Die vollständigen quiCkLI-Bausteine​

Lies die Konzept-Referenz für die vollständige API-Dokumentation oder erkunde die Implementierungsleitfäden für schrittweise Anleitungen.

CLIs also create durable interfaces between people, scripts, services, and infrastructure. Their limitations are real, but a focused command with predictable text and exit behavior can remain useful for years.

Good agent-facing CLIs still need careful schemas, validation, idempotence, useful errors, and permissions. The command line is not automatically safe, but it is a practical surface for making tool behavior visible to both people and agents.