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.

This comprehensive guide will help you set up and understand Sayer.

We'll walk you through installation, project creation, and writing your first commands, all with explanations, examples, and common pitfalls.

Prerequisites¶

Before you begin, ensure you have:

• Python 3.10 or higher installed.
• A terminal/command prompt.
• A basic understanding of Python and CLI concepts.

Installation¶

Install Sayer using pip:

pip install sayer

If you encounter permission errors, try:

pip install --user sayer

Or use a virtual environment:

python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate
pip install sayer

Creating a New CLI Project¶

Sayer can scaffold a complete project structure with one command:

sayer new myapp

This creates the following structure:

myapp/
├── main.py            # Entry point for your CLI
├── commands/          # Directory for your custom commands
│   └── __init__.py
├── pyproject.toml     # Project metadata
├── README.md
└── .gitignore

What to do:

• Edit main.py to define your commands.
• Add new modules under commands/ to organize functionality.

What NOT to do:

• Don't modify pyproject.toml unless you understand Python packaging.
• Avoid hardcoding absolute paths inside your CLI; use dynamic paths.

Writing Your First Command¶

Open main.py and add a basic command:

from sayer import Sayer, command

app = Sayer()

@app.command()
def hello(name: str):
    """Say hello to a user by name."""
    print(f"Hello, {name}!")

if __name__ == "__main__":
    app()

Run it:

python main.py hello --name Alice

Output:

Hello, Alice!

Understanding the Code¶

• Sayer() creates the CLI app.
• @app.command() decorates the hello function to expose it as a CLI command.
• The name parameter is automatically parsed from --name.
• if __name__ == "__main__": app() runs the CLI when the script is executed.

Best Practices¶

• ✅ Use clear and concise help strings (docstrings) for commands.
• ✅ Test your commands with various argument combinations.
• ❌ Avoid complex logic inside commands; delegate to helper functions.
• ❌ Don't assume name will always be provided – consider adding defaults.

Next Steps¶

• Explore API Reference for detailed module docs.
• Learn about Middleware for hooks and validation.
• Add complex parameters and encoders for advanced use cases.

With Sayer, you're not just writing a CLI – you're building a robust, maintainable, and user-friendly command-line application. Let's get started!