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
LGPLv3 License — Built with pure Python standard library:
| Module | Purpose |
|---|---|
sys |
Argument parsing |
asyncio |
Async command execution |
inspect |
Signature introspection |
Author: Fkernel653 Project: GitHub • PyPI
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
cliss-1.2.4.tar.gz
(14.0 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
cliss-1.2.4-py3-none-any.whl
(18.0 kB
view details)
File details
Details for the file cliss-1.2.4.tar.gz.
File metadata
- Download URL: cliss-1.2.4.tar.gz
- Upload date:
- Size: 14.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e1a1f047f52838692d17f4eec516779ef202fc4dcdb9c600732de98f034b554c
|
|
| MD5 |
3ff4f82d261fd2c542ba67e29cead196
|
|
| BLAKE2b-256 |
5349749383fbc8bedf432a41ff48416a66ad0aacf5e124eff7d0c80381843cf7
|
File details
Details for the file cliss-1.2.4-py3-none-any.whl.
File metadata
- Download URL: cliss-1.2.4-py3-none-any.whl
- Upload date:
- Size: 18.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f413b7471623af5d5217514486e0dd26a06a4a983e48b519b37d58c9161d8244
|
|
| MD5 |
11eeec446c674761671740298fbe45d1
|
|
| BLAKE2b-256 |
9b3197ed0f00d0ddd091442bc8d2b1f18b04fb02c091fce5f1d2a2e7fd659a3d
|
