arg-kiss — Keep It Stupidly Simple CLI builder on top of argparse

Write type-annotated Python functions, get a CLI with argparse's native --help — no magic, no bloat.

🚀 Quick Start

pip install arg-kiss                    # Python 3.10+

from arg_kiss import Argkiss

cli = Argkiss(name="todo", description="Task manager", color=True)


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


@cli.command()
def list_all():
    """Show all tasks."""
    print("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 [-h] {add,list-all} ...

Task manager

positional arguments:
  {add,list-all}
    add           Add a task.
    list-all      Show all tasks.

options:
  -h, --help      show this help message and exit

📋 Commands & Features

@cli.command() — Define commands from functions

@cli.command()
def fetch(url: str, retries: int = 3):
    """Download from URL with retries"""
    print(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("-u", "--user", help="Username")
@cli.argument("-p", "--port", type=int, default=8080, help="Port number")
@cli.argument("--ssl", action="store_true", help="Enable SSL")
@cli.command()
def connect(user: str, port: int = 8080, ssl: bool = False):
    """Connect to server"""
    print(f"Connecting as {user} on port {port} (SSL: {ssl})")

Type → CLI mapping

Boolean flags — Two modes

By default, boolean parameters get --flag/--no-flag pairs:

cli = Argkiss(name="app", boolean_optional=True)  # default


@cli.command()
def run(verbose: bool = False):
    """Run with --verbose or --no-verbose"""

To disable and use simple --flag with store_true/store_false:

cli = Argkiss(name="app", boolean_optional=False)


@cli.command()
def run(verbose: bool = False):
    """Run with --verbose to enable"""

Command groups

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


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


@remote.command()
def remove(name: str):
    print(f"Removed remote {name}")

Usage:

$ python app.py remote add origin https://github.com/user/repo
Added remote origin -> https://github.com/user/repo

$ python app.py remote remove origin
Removed remote origin

Global arguments (apply to all commands)

cli.add_global_argument("--verbose", "-v", action="store_true", help="Verbose output")
cli.add_global_argument("--config", "-c", type=str, help="Config file path")


@cli.command()
def deploy(environment: str):
    """Deploy to environment."""
    # Global arguments available in parsed namespace
    pass

Async support

@cli.command()
async def fetch(url: str, retries: int = 3):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        print(f"Status: {r.status_code}")

🎨 CLI Configuration

cli = Argkiss(
    name="myapp",  # Program name (default: None)
    description="Does amazing things",  # Description in help (default: None)
    version="2.0.0",  # Adds --version flag (default: None)
    color=True,  # ANSI colours (default: True)
    boolean_optional=True,  # --flag/--no-flag for bools (default: True)
)

Disable colours via environment

NO_COLOR=1 python myapp.py --help

📄 License & Acknowledgments

LGPLv3 License — Built with Python standard library:

Author: Fkernel653 Project: GitHub • PyPI