cliss 1.2.1

Write type-annotated Python functions, get a full CLI — automatic `--help`, validation, async support, and zero dependencies

cliss — Lightweight framework for building CLI applications

Write type-annotated Python functions, get a full CLI — automatic --help, validation, async support, and zero dependencies.

🚀 Quick Start

pip install cliss                    # Python 3.10+

from cliss import Cliss

cli = Cliss(name="todo", description="Task manager", version="1.0.0")

@cli.command()
def add(task: str, priority: int = 1, done: bool = False):
    """Add a task."""
    status = "✓" if done else "○"
    return f"[{status}] {task} (priority: {priority})"

@cli.command()
def list_all():
    """Show all tasks."""
    return "Nothing yet!"

cli()

$ python todo.py add "Buy milk" --priority 2
[○] Buy milk (priority: 2)

$ python todo.py list-all
Nothing yet!

$ python todo.py --help
Usage: todo [COMMAND] [OPTIONS] [ARGS]...

Task manager

Commands:
  add           Add a task.
  list-all      Show all tasks.

Options:
  -V, --version Print version info and exit
  -h, --help    Print help

📋 Commands & Features

@cli.command() — Define commands from functions

@cli.command()
def fetch(url: str, retries: int = 3):
    """Download from URL with retries"""
    return f"Fetched {url} (retries: {retries})"

@cli.argument() — Customize argument flags

Use @cli.argument() above @cli.command() to customize flags, help text, and behavior for individual parameters.

@cli.argument("-v", "--verbose", help="Enable verbose output")
@cli.argument("-r", "--retries", type=int, help="Number of retries")
@cli.command()
def fetch(url: str, verbose: bool = False, retries: int = 3):
    """Download from URL"""
    return f"Fetched {url} (retries: {retries})"

Type → CLI mapping

Function signature	CLI argument
name: str	Positional name
count: int = 1	--count (default: 1)
verbose: bool = False	--verbose / --no-verbose
mode: str = None	--mode (default: None)

Boolean flag behavior

Function signature	Help display	Usage
flag: bool	--flag, --no-flag (required)	--flag or --no-flag
flag: bool = False	--flag (default: disabled)	--flag enables, --no-flag also works
flag: bool = True	--no-flag (default: enabled)	--no-flag disables, --flag also works

Command groups

remote = cli.group("remote", "Manage remotes")

@remote.command()
def add(name: str, url: str):
    return f"Added remote {name}"

Async support

@cli.command()
async def fetch(url: str, retries: int = 3):
    return f"Fetched {url} (retries: {retries})"

🎨 CLI Configuration

cli = Cliss(
    name="myapp",                      # Program name in help
    description="Does amazing things", # Description in help
    version="2.0.0",                   # Adds --version flag
    color=False,                       # Disable ANSI colours
)

Option	Description
name	Program name in help
description	Description in help
version	Adds --version flag
usage	Custom usage string
color	Enable/disable ANSI colours (default: True)

Disable colours via environment

NO_COLOR=1 python myapp.py --help

📄 License & Acknowledgments

MIT License — Built with pure Python standard library:

Module	Purpose
sys	Argument parsing
asyncio	Async command execution
inspect	Signature introspection

Author: Fkernel653 Project: GitHub • PyPI