quiCkLI

quiCkLI is a minimal, educational Python framework for building command-line interfaces. It keeps application structure, parsing, validation, configuration, plugins, and shell completion explicit and readable.

The Python package and distribution name is quickli. The stylized project name is quiCkLI.

Current capabilities

• commandless applications with @app.entrypoint(...)
• named commands and subcommands for multi-command applications
• positional arguments, options, flags, repeatable values, and global options
• type conversion and validators for files, directories, positive numbers, and ranges
• automatic application, command, and nested --help/-h with docstring fallback
• JSON, YAML, and TOML loading and rendering helpers
• YAML/JSON/TOML configuration schemas, validation, and JSON Schema generation
• opt-in init command and explicit app.init_config() with custom configuration defaults
• explicit plugin registration and loading
• Bash, PowerShell, and ZSH completion generation
• executable-shell output with structured quickli errors and JSON mode

The core API accepts explicit argument tokens through Application.run(). For executable programs, Application.main() reads sys.argv by default, prints results, maps failures to quickli errors, and returns process-friendly exit codes.

Quick example

from quickli import Application, Argument, Option

app = Application(name="hello", description="Greet a person.")


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


print(app.run(["Ada", "--uppercase"]))

Inspect usage without invoking the handler with print(app.run(["--help"])). For named commands, use app.run(["command", "-h"]). Explicit aliases remain available to your options; Application("hello", auto_help=False) disables automatic help.

For an executable shell:

import sys


if __name__ == "__main__":
    sys.exit(app.main())

Repository layout

• packages/core: the Python package, tests, examples, specifications, and developer documentation
• packages/quickli-docs: the Docusaurus documentation site
• .github: CI, coverage, release automation, and repository guidance

Installation and development

For local development:

cd packages/core
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"

Run the core checks from packages/core:

python -m pytest
python -m ruff check .
python -m ruff format --check .

The repository requires Python 3.12, 3.13, or 3.14. The project uses pytest for tests; Ruff, coverage, and build are development dependencies.

Documentation

• Documentation site
• Documentation package
• Python package README
• Getting started guide
• Core concepts
• Configuration and initialization
• Logging guide
• Packaging, executable binaries, and containers
• Examples
• Specifications
• Architectural decisions

Start the documentation site from the repository root with:

pnpm install
pnpm --filter quickli-docs start

Build it with:

pnpm --filter quickli-docs build

The site currently supports English and German locales.

Project status

quiCkLI is in alpha. The implementation, tests, specifications, and examples are being developed together as an educational reference project. Release automation uses Release Please; the core package is published to PyPI and the documentation site is deployed to GitHub Pages.

The documentation describes the current source checkout. When trying unreleased additions, install it with python -m pip install -e packages/core from the repository root. Do not assume the latest PyPI release already includes every documented change.

License

quiCkLI is licensed under the MIT License.