argss 0.2.2

Write type-annotated Python functions, get a CLI with argparse's native `--help` — no magic, no bloat. Flat commands only, synchronous execution

argss — Stupidly Simple CLI builder (sync-only, no groups)

argss is a lightweight fork of arg-kiss — stripped down to the essentials.

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

🎯 Why argss?

Feature	arg-kiss	argss
@cli.command()	✅	✅
@cli.argument()	✅	❌
arguments parameter in @cli.command()	✅	✅
Type inference	✅	✅
Boolean flags	✅	✅
Global arguments	✅	✅
Command groups	✅	❌
Async support	✅	❌
color parameter (Python 3.14+ coloured help)	✅	❌
Dependencies	none	none

Use argss when you want:

• Minimal code footprint
• No asyncio overhead
• Flat command structure (no sub-subcommands)
• Faster import time (~30% faster than arg-kiss)

🚀 Quick Start

pip install argss

from argss import Argss

cli = Argss(name="todo", description="Task manager")

@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.run()

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

Custom arguments with arguments parameter

Override default argument generation and add short flags, custom help text, or other argparse options:

@cli.command(arguments=[
    ["-n", "--name", {"type": str, "help": "Your name", "required": True}],
    ["-v", "--verbose", {"action": "store_true", "help": "Enable verbose output"}],
    ["-r", "--retries", {"type": int, "help": "Number of retries", "default": 3}],
])
def greet(name: str, verbose: bool = False, retries: int = 3):
    """Greet someone."""
    msg = f"Hello, {name}!"
    if verbose:
        msg += f" (retries: {retries})"
    print(msg)

$ python script.py greet -n "Alice" -v -r 5
Hello, Alice! (retries: 5)

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

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

🎨 CLI Configuration

cli = Argss(
    name="mycli",                       # Program name (default: None)
    description="Does amazing things",  # Description in help (default: None)
    version="2.0.0",                    # Adds --version flag (default: None)
)

Option	Description
name	Program name in help (default: None)
description	Description in help (default: None)
version	Adds --version flag (default: None)

📄 License & Acknowledgments

MIT License — Built with Python standard library:

Module	Purpose
argparse	CLI parsing engine
inspect	Signature introspection

Forked from: arg-kiss by Fkernel653

argss author: Fkernel653

Project: GitHub • PyPI