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.

In this first article of the Getting Started with quiCkLI series you will build a greeting tool with exactly three concepts: Application, Argument, and Option.

What you will build​

$ python hello.py Ada
$ Hello, Ada!

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

A single file. No configuration. Under thirty lines of Python.

Prerequisites​

Install quickli in a virtual environment:

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

You need Python 3.12 or later.

Step 1: Create the application​

from quickli import Application

app = Application(
    name="hello",
    description="Greet a person from the command line.",
)

Application is the root container. It owns command registration and dispatch. You give it a name (used in help output) and a short description.

Step 2: Register a handler​

from quickli import Application, Argument, Option

@app.entrypoint(
    help_text="Print a greeting.",
    arguments=[Argument("name", help_text="Name to greet.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Print the greeting in uppercase.",
        ),
    ],
)
def greet(name: str, uppercase: bool = False) -> str:
    message = f"Hello, {name}!"
    return message.upper() if uppercase else message

@app.entrypoint registers a function as the single handler for this application.

• Argument("name") declares a required positional value. quickli passes it directly to the name parameter of your function.
• Option("uppercase", is_flag=True) declares a boolean flag. Present → True, absent → False.

Step 3: Run the application​

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

Application.run() reads sys.argv[1:] by default and returns the handler result. You decide what to do with it - in this case, you print it.

The full file​

from __future__ import annotations

from quickli import Application, Argument, Option


app = Application(
    name="hello",
    description="Greet a person from the command line.",
)


@app.entrypoint(
    help_text="Print a greeting.",
    arguments=[Argument("name", help_text="Name to greet.")],
    options=[
        Option(
            "uppercase",
            short_name="u",
            is_flag=True,
            help_text="Print the greeting in uppercase.",
        ),
    ],
)
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())

Try it​

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

What you learned​

• Application owns registration and dispatch.
• @app.entrypoint registers a single handler for the whole application.
• Argument describes positional, required input.
• Option with is_flag=True adds a boolean switch.
• Application.run(argv) returns the result - you control output.

Next in this series​

The next article adds file input, validation, and global options by building a small file viewer inspired by the Unix cat command.

📖 Part 2: Reading Files - the quickcat tool →

This post answers that question honestly. It is the first in a series about the development of quiCkLI - what it is, why it exists, and where it is going.

The gap I wanted to fill​

I wanted a framework I could point a learner at and say: all the important parts are visible here. When I tried to explain how a CLI application works using an existing framework, I kept running into the same problem. The framework was good at hiding complexity - which is great for production code - but that same hiding made it hard to understand what was actually happening.

click, for example, uses a layered decorator model that works beautifully in practice but abstracts away how arguments are collected, how defaults are resolved, and how subcommands are dispatched. That abstraction is valuable. It is also precisely what makes it hard to learn from.

I did not want to replace any of these tools. I wanted to build something that could serve as a reference implementation - a framework small enough that a developer could read the entire source in an afternoon and understand how a CLI is assembled from first principles.

What "minimal" means here​

quickli is not minimal because it has fewer features. It is minimal in the sense that every part of the design is deliberate and visible.

• The application container owns registration and dispatch. That boundary is explicit.
• Arguments are positional and ordered. Options are named. Those are different things.
• Conversion and validation are separate steps, and they happen before the handler runs.
• The framework returns results to the caller. It reads sys.argv[1:] by default, but does not print output or handle exit codes.

Each of these decisions was made because it keeps the mechanics of a CLI visible to someone learning how they work.

The guiding question​

For every feature I considered adding to quickli, I asked the same question: does this make the framework easier to learn from, or does it make it more powerful at the cost of making it harder to understand?

That question has kept quickli small. It has also forced me to be explicit about what the framework is not trying to do.

What comes next​

The next post in this series looks at who quiCkLI is for - the target audience, and what I am hoping they get out of using it.

📖 Part 2: Who Is quiCkLI For? →

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.

The example is quickcat, a minimal file viewer modeled after the Unix cat command.

What you will build​

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

New concepts​

Global options​

app = Application(
    name="quickcat",
    description="A tiny cat-like CLI built with quickli.",
    global_options=[
        Option("verbose", short_name="v", is_flag=True, help_text="Enable verbose output."),
    ],
)

Global options live on Application, not on an individual command. They can appear before or after the command name on the command line, and every handler that wants them declares the matching parameter.

The file_path validator​

Argument("path", help_text="Primary file path.", validators=[file_path()]),

file_path() is a built-in validator factory. It returns a callable that quickli runs after parsing but before calling your handler. If the path does not exist or is not a file, execution stops with a clear error message - your handler never sees an invalid value.

You can pass multiple validators in the list; they run left to right.

Repeatable options​

Option(
    "include",
    short_name="i",
    multiple=True,
    validators=[file_path()],
    help_text="Additional file paths to print after the primary file.",
),

multiple=True lets users pass the option more than once:

$ python quickcat.py main.py -i utils.py -i helpers.py

The handler receives include as list[Path] | None. When absent, it is None.

The full example​

from __future__ import annotations

from pathlib import Path

from quickli import Application, Argument, Option, file_path


app = Application(
    name="quickcat",
    description="A tiny cat-like CLI built with quickli.",
    global_options=[
        Option("verbose", short_name="v", is_flag=True, help_text="Enable verbose output."),
    ],
)


@app.entrypoint(
    help_text="Print one or more text files to stdout.",
    arguments=[
        Argument("path", help_text="Primary file path.", validators=[file_path()]),
    ],
    options=[
        Option("encoding", short_name="e", default="utf-8", help_text="Text encoding."),
        Option("number", short_name="n", help_text="Print line numbers.", is_flag=True),
        Option(
            "include",
            short_name="i",
            multiple=True,
            validators=[file_path()],
            help_text="Additional file paths to print after the primary file.",
        ),
    ],
)
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())

What you learned​

• global_options on Application declare options available to every handler.
• file_path() validates that a value is an existing, readable file.
• multiple=True accumulates repeated option values into a list.
• Validators run before the handler, keeping the handler body clean.

Next in this series​

The final article builds a kubectl-like multi-command application with @app.command, custom validator factories, and CommandExecutionError.

📖 Part 3: Multi-Command Applications →

The primary audience​

quiCkLI is for developers who want to understand how a command-line application is assembled - not just use one.

That group includes:

• Students and early-career developers building their first command-line tools. They need a framework where the mechanics are visible, not hidden behind a polished abstraction.
• Developers coming from other languages who want to understand the Python approach to CLI design without reading the source of a large framework.
• Experienced developers who want a small, readable reference implementation to use as a teaching aid or a starting point for their own experiments.

Who quiCkLI is not for​

If you are building a production CLI tool and you need shell completion, nested subcommands, configuration files, and a rich help renderer, use click or typer. They are excellent tools built for exactly that purpose.

quiCkLI makes explicit tradeoffs that would be unacceptable in a production framework:

• It reads sys.argv[1:] by default, but lets you opt out with auto_sys_argv=False.
• It does not print output or choose exit codes.
• It does not provide shell completion.
• Its plugin discovery is manual.

These are not oversights. They are deliberate choices that keep the parts visible.

What the target audience needs​

A learner needs:

1. A small surface area. If the framework has twenty classes, understanding it requires understanding all twenty. quickli has five core concepts. You can hold the whole model in your head.
2. Explicit boundaries. Where does the framework end and the application begin? In quickli, that boundary is Application.run(). The application receives a result back. Everything that happens to process exit codes and output formatting is the application's responsibility.
3. Runnable examples. Theory is not enough. The reference examples in the repository are real, runnable tools that demonstrate each concept in context.

What this means for the project​

Keeping quiCkLI useful for learners means resisting the natural impulse to add features. Every feature adds surface area. Every abstraction hides something.

The project's quality bar is not just does it work - it is is it still easy to understand. That is a harder standard to maintain, and it is the one that matters most for this audience.

By the end you will understand every primitive in quickli and how they fit together in a realistic application.

What you will build​

$ 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​

Until now you used @app.entrypoint, which registers a single handler for the whole application. When you need multiple commands, use @app.command instead:

@app.command(
    name="get",
    help_text="List resources in the selected namespace.",
    arguments=[...],
    options=[...],
)
def get(resource: str, ...) -> str:
    ...

The name parameter becomes the first token on the command line. Omitting name uses the function name. You can register as many commands as you need.

Custom validator factories​

quickli ships with built-in validators (file_path, positive_number, and others), but you can write your own using the same pattern:

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

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

    validate.description = description
    return validate

A validator factory returns a callable that:

1. Receives the converted value.
2. Returns the value unchanged if it is valid.
3. Raises ValueError with a clear message if it is not.

Setting validate.description provides the text that appears in help and error output.

CommandExecutionError​

CommandExecutionError is for expected domain-level failures - not programming errors:

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}' was not found in namespace '{namespace}'."
    )

This exception propagates unchanged out of Application.run(). Your application wrapper can catch it and turn it into an exit code:

import sys
try:
    print(app.run())
except quickli.CommandExecutionError as error:
    print(f"Error: {error}", file=sys.stderr)
    sys.exit(1)

Global options shared across commands​

Declare options once on Application. Every command handler that needs them declares the same parameter name:

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),
    ],
)

@app.command(name="get", ...)
def get(resource: str, namespace: str = "default", output: str = "table",
        verbose: bool = False) -> str:
    ...

@app.command(name="describe", ...)
def describe(resource: str, name: str, namespace: str = "default",
             verbose: bool = False, output: str = "table") -> str:
    ...

quickli matches global option names to parameter names for each command.

Full source​

The complete example is at packages/core/examples/complex/pyk5l/app.py. Try it:

$ git clone https://github.com/spmse/quickli.git
$ cd quickli
$ pip install -e packages/core
$ cd packages/core/examples/complex/pyk5l
$ python app.py get pods

What you learned​

• @app.command registers named commands in a multi-command application.
• Custom validator factories follow the same pattern as built-in validators.
• CommandExecutionError signals expected domain-level failures.
• Global options declared on Application are available to every command handler.

The complete quiCkLI primitives​

Read the concept reference for the full API or explore the implementation guides to follow along with each example in detail.

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.