Sayer

Fast. Scalable. Elegant. Command the CLI like a boss. 🧙‍♂️

---

Documentation: https://sayer.dymmond.com 📚

Source Code: https://github.com/dymmond/sayer

The official supported version is always the latest released.

---

🤔 What is Sayer?

Sayer is a modern, async-native Python CLI framework built for developers who want more:

• More structure.
• More power.
• More expressiveness.

Less boilerplate. Less headache. Less "why doesn't this just work?".

Designed to scale from weekend scripts to enterprise-grade CLI suites — with a touch of magic.

---

📦 Installation

Using pip:

pip install sayer

Or with uv (blazing fast):

uv pip install sayer

---

🧩 Features

• ✅ Fully async support out-of-the-box
• ✅ Param metadata via Option(...), Argument(...), Env(...) — inspired by the best
• ✅ Declarative CLI building with decorators
• ✅ Built-in middleware system (yes, for CLI!)
• ✅ Shared app state and lifecycle management
• ✅ Terminal-rich output via rich
• ✅ Easy testing with SayerTestClient
• ✅ Flexible help and docs rendering
• ✅ Clean project scaffolding, sensible defaults
• ✅ 100% type annotated.

---

🔥 Why Sayer?

Feature	Sayer	Notes
Async Support	✅ Yes	Truly async from top to bottom
Param Metadata	✅ Yes	With rich options, env vars, etc.
Middleware Support	✅ Yes	Per-command, app-wide, scoped
Lifecycle Hooks	✅ Yes	on_startup, on_shutdown
State Management	✅ Yes	Like a Flask g but better
Testability	✅ Yes	CLI client for unit tests
Output Styling	✅ Yes	Built-in rich integration
Based on Modern Tools	✅ Hatch + UV	Modern dev setup from day 1
Full Typing	✅ Yes	Mypy + Ruff compliant
Fun to Use?	🕺 Extremely	Let the code dance with you

---

🚀 Getting Started

Create your first CLI app:

from sayer import Sayer, Option

app = Sayer()

@app.command()
def hello(name: str = Option(..., help="Your name")):
    """Say hello to someone"""
    print(f"Hello, {name}!")

if __name__ == "__main__":
    app()

Run it:

$ python app.py hello --name Ada
Hello, Ada!

---

🧪 Testing

hatch run test:test

Or with pytest:

pytest -v

---

📚 Documentation

Full docs available at: https://sayer.dymmond.com

You'll find:

• Full API reference
• Command examples
• Parameter deep dives
• Middleware patterns
• Configuration strategies
• ... and some fun easter eggs 🐣