tiny-cli

Zero-dependency CLI builder for Python. Decorators, color, prompts — argparse without the bloat.

pip install tiny-cli   # coming soon

Why?

• argparse — verbose, no colors, no prompts
• click — 1 dep (markupsafe), heavy
• typer — 6 deps, requires pydantic + click

tiny-cli is ~250 lines, zero deps, gives you the 90% case: commands, options, color, prompts.

Usage

import tiny_cli as tc
import sys

app = tc.App(name="mytool", help="My CLI tool")

@app.command(help="Greet someone.")
def greet(
    name: str,
    times: int = tc.option("--times", "-n", default=1, type=int, help="how many times"),
    shout: bool = tc.option("--shout", "-s", default=False, type=bool, help="uppercase"),
):
    msg = f"Hello, {name}!" * times
    if shout:
        msg = msg.upper()
    tc.echo(tc.style.green(msg))

@app.command(help="Add two numbers.")
def add(a: float, b: float):
    tc.echo(tc.style.cyan(f"{a} + {b} = {a + b}"))

@app.command(help="Destructive operation with confirmation.")
def rm(path: str, force: bool = tc.option("--force", "-f", default=False, type=bool)):
    if not force and not tc.confirm(f"Really delete {path}?"):
        tc.echo("aborted")
        return
    tc.echo(f"removing {path}")

sys.exit(app.run())

$ mytool greet alice --shout --times 3
HELLO, ALICE!HELLO, ALICE!HELLO, ALICE!

$ mytool add 2 3
2.0 + 3.0 = 5.0

$ mytool rm /etc/passwd
? Really delete /etc/passwd? [y/N]:

API

Function	Description
App(name, help, version)	CLI app container
@app.command(name, help)	Register a subcommand
option(*flags, default, type, help, choices)	Mark param as --flag option
argument(name, type, default, help)	Mark param as positional
echo(text)	Print to stdout (TTY-colored when available)
confirm(question, default)	Yes/no prompt
prompt(question, type, choices, password)	Typed prompt
style.red/green/blue/bold/...	ANSI color helpers

Color & TTY

Colors auto-disable when stdout isn't a TTY or NO_COLOR env is set (12-factor friendly).

tc.echo(tc.style.red("error: ", color=True) + "file not found")

Agent Workflow Fit

tiny-cli is a good fit for the command surfaces that autonomous agents keep creating around small tools:

• One-shot maintenance commands — wrap cleanup, sync, scan, and report scripts with typed arguments.
• Bounty repro CLIs — package a reproducible exploit/checker script without adding Click or Typer.
• Cron companions — expose run, status, dry-run, and repair commands for scheduled jobs.
• Operator prompts — use confirm() and prompt() for rare destructive or ambiguous local actions.

Pair it with tiny-config for layered settings, tiny-log for machine-readable output, and tiny-timeout for commands that call flaky services.

Benchmarks

== tiny-cli benchmarks (n=10,000) ==
  style.red                       0.214 µs/op
  style.green                     0.207 µs/op
  style.bold                      0.211 µs/op
  _coerce (int)                   0.487 µs/op
  _coerce (bool)                  0.391 µs/op
  _coerce (list)                  3.142 µs/op

Tests

python test_tiny_cli.py
# Ran 14 tests in 0.004s — OK

Ecosystem

Part of the tiny-* zero-dependency toolkit for Python agent infrastructure:

• tiny-router — HTTP router, 76K req/s
• tiny-log — structured logging
• tiny-validator — input validation, 247K val/s
• tiny-config — layered config loader
• tiny-cli — CLI builder with colors
• fast-cache — LRU + TTL + SWR cache
• tiny-rate — rate limiter (token / fixed / sliding)
• tiny-retry — retry + backoff + circuit breaker
• tiny-pool — ThreadPool + AsyncPool
• tiny-agent — zero-dep agent framework
• tiny-mcp — Model Context Protocol
• tiny-embed — embeddings + vector search
• tiny-compose — Stack any decorators in any order, declaratively
• tiny-trace — OTel-compatible tracing, sync + async, W3C propagation
• tiny-secret — Zero-dep secret loader + redacting printer
• tiny-cron — cron-style scheduler + intervals
• tiny-flags — feature flags, percentage rollout
• tiny-queue — persistent FIFO queue, retries
• tiny-metrics — Prometheus-compatible metrics
• tiny-timeout — hard timeouts + cooperative deadlines
• tiny-idempotency — Stripe-style idempotency keys
• tiny-budget — runtime cost + token enforcement for AI agents
• tiny-eventbus — durable pub/sub with JSONL replay
• snapdb — embedded DB

21 repos, ~14,700 LOC, zero dependencies across the entire stack. All single-file, MIT, fully type-hinted. Built by OpenClaw.

Reports

• Agent Operator CLI Pattern — typed command boundaries for scan, verify, report, and publish loops in autonomous developer workflows.

License

MIT © 2026 OpenClaw (hussain-alsaibai)