cliss 0.8.2

A lightweight framework for building CLI applications on top of argparse

cliss — A lightweight framework for building CLI applications on top of argparse

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

✨ Features

• Zero Dependencies — Pure stdlib: argparse, asyncio, inspect
• Type-Driven — Automatic arguments from function signatures and type hints
• Flexible — Declarative Argument objects, type inference, or both
• Async-Native — async def handlers with automatic event loop management
• Global Args — Define flags shared across all commands
• Coloured Help — Beautiful terminal output via ANSI-codes
• Bool Flags — Automatic --name/--no-name mutually exclusive group
• argparse Access — Full access to underlying parsers for advanced use

🚀 Quick Start

Installation

pip install cliss

Usage

from cliss import CLI

cli = CLI(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.run()

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

$ python todo.py add "Call mom" --done
[✓] Call mom (priority: 1)

$ python todo.py add "Test" --no-done
[○] Test (priority: 1)

📋 API Reference

CLI class

CLI(name="myapp", description="...", version="1.0.0")

Parameter	Type	Default	Description
name	str	None	Program name in help
description	str	None	Description in help
version	str	None	Adds --version flag
usage	str	"{self.name} [COMMAND] [OPTIONS] [ARGS]...\n"	Custom usage string

Argument class

from cliss import Argument

Argument("--output", "-o", type=str, default=None, help="...", choices=["json","csv"], action="store_true")

Parameter	Type	Default	Description
*flags	str	—	Argument flags
type	type	str	Value type
default	Any	None	Default value
help	str	""	Help text
required	bool	False	Make required
choices	list	None	Allowed values
action	str	None	argparse action

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)

📖 Examples

CRUD Application

from cliss import CLI

cli = CLI(name="db")
db = {}

@cli.command()
def set(key: str, value: str):
    db[key] = value
    return f"OK: {key} = {value}"

@cli.command()
def get(key: str):
    return db.get(key, "Not found")

@cli.command()
def delete(key: str, force: bool = False):
    if force or key in db:
        db.pop(key, None)
        return f"Deleted: {key}"
    return f"Not found (use --force)"

cli.run()

Command Groups

cli = CLI(name="git")

remote = cli.group("remote", "Manage remotes")
stash = cli.group("stash", "Stash changes")

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

@stash.command()
def push(message: str = ""):
    return f"Stashed: {message or 'WIP'}"

cli.run()

Async Commands

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

❓ FAQ

Why cliss over argparse/Click/Typer/Fire?

Tool	Deps	Style
cliss	0	Decorators + type hints
Fire	1 (termcolor)	Introspection
Click	0	Decorators
Typer (0.26.0+)	0	Type hints

cliss = Fire's zero-bloat philosophy + Typer's type-driven design. ~300 lines, pure stdlib, ANSI-codes for pretty output.

Bool flags?

Automatic --name/--no-name mutually exclusive group. store_true by default, store_false if default is True.

Async?

async def handlers auto-run with asyncio.run(). Sync functions returning coroutines also work.

argparse access?

cli.parser and cli.subparsers are standard argparse objects. Mutually exclusive groups, custom actions, parent parsers — all available.

📄 License

MIT — see LICENSE file.

---

Author: Fkernel653 Repository: github.com/Fkernel653/cliss PyPI: pypi.org/project/cliss