arg-kiss 0.2.4

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

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 CLI

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

📋 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})")

Type → CLI mapping

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

Command groups

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

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

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 = CLI(
    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=False,                       # Disable ANSI colours (default: True)
)

Option	Description
name	Program name in help (default: None)
description	Description in help (default: None)
version	Adds --version flag (default: None)
color	Enable/disable coloured output (default: True)

Disable colours via environment

NO_COLOR=1 python myapp.py --help

📖 Examples

CRUD Application

from arg_kiss import CLI

cli = CLI(name="db", description="Simple database")
db = {}

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

@cli.command()
def get(key: str):
    """Retrieve a value."""
    print(db.get(key, "Not found"))

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

cli.run()

Command Groups (nested subcommands)

cli = CLI(name="git", description="Version control")

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

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

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

cli.run()

📄 License & Acknowledgments

MIT License — Built with Python standard library:

Module	Purpose
argparse	CLI parsing engine
asyncio	Async command execution
inspect	Signature introspection

Author: Fkernel653 Project: GitHub • PyPI