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.

Source checkout versus released package

These pages follow the current source checkout. New initialization and automatic-help APIs may not yet be in the latest PyPI release. To try unreleased behavior, use the editable repository installation below; for production, select and test a published version.

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

import sys

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. For this entrypoint, name is required; running without arguments reports a missing argument. Use an automatic help flag to inspect usage without invoking the handler:

python hello.py --help
python hello.py -h

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.

Help flags

--help and -h work automatically. Named commands support mytool command --help too. Applications without an entrypoint return help when called with no tokens; entrypoint applications still execute their handler unless a help flag is supplied. See Automatic help for custom alias handling.

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.
• Define persistent settings with configuration schemas and initialization.
• Add diagnostics using the logging guide.
• Distribute your CLI using the packaging guide.
• Read the project examples for small, focused applications.