Getting Started

This guide creates a small command-line application with one entrypoint, one positional argument, and one flag. quickli supports Python 3.12, 3.13, and 3.14.

Install quickli

For a project using the released package, install quickli in a virtual environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install quickli

When working from the quickli repository, install the package in editable mode instead:

python -m pip install -e packages/core

Add to your project

Start where you are.

Add quickli to an existing Git project, or create a clean project to experiment with the framework.

Existing project

Add quickli to Git

Keep your current project and install quickli into its virtual environment.

pip

Terminal

pip install quickli

uv

Terminal

uv add quickli

New project

Initialize a workspace

Create a small Git project, then add quickli as its first dependency.

pip

Terminal

mkdir my-cli && cd my-cli
git init
python -m venv .venv
source .venv/bin/activate
python -m pip install quickli

uv

Terminal

mkdir my-cli && cd my-cli
git init
uv init
uv add quickli

Prefer a guided walkthrough? Continue to the Getting Started guide.

Create an application

Save this example as hello.py:

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__":
    sys.exit(app.main())

Run it

Pass the command-line tokens to the application:

python hello.py Ada
python hello.py Ada --uppercase

The first command prints Hello, Ada!; the second prints HELLO, ADA!.

Explore generated help

The application generates help from its registered arguments and options. Run it without arguments to see the usage text:

python hello.py

Application.main() is the beginner-friendly executable entrypoint. It reads sys.argv[1:] for you, prints the returned value, reports quickli runtime errors, and returns an exit code.

Application.run() still returns the handler result for tests, libraries, and other code that wants direct control. It also reads sys.argv[1:] by default when you call it without arguments. Pass an explicit list to override or set auto_sys_argv=False to disable automatic reading.

Where to go next

• Use @app.command() to build a multi-command CLI.
• Use converter=int or converter=Path to convert input values.
• Add validators such as file_path() or number_range() for checked input.
• Read the project examples for small, focused applications.