CliFire

Minimal CLI framework to build Python commands quickly and elegantly.

CliFire is a lightweight Python library designed to simplify the creation of command-line interfaces (CLI). It allows developers to define commands, options, and arguments in a straightforward way, making it easy to build complex CLI applications without the overhead of bigger frameworks.

Key Features

• Two Usage Styles: Define commands using decorators or classes.
• Intuitive Syntax: Focus on writing application logic without worrying about CLI infrastructure.
• Arguments & Options: Flexible parsing with positional arguments and command options.
• Grouped Commands: Organize related commands using a dot-based naming convention.
• Formatted Output: Leverage the Rich library for colorful and styled messages.
• Templates: Generate files using Jinja2 templates.
• Centralized Configuration: Manage configuration via YAML using the Config module.

Installation

Install CliFire using pip:

pip install clifire

Or with Poetry:

poetry add clifire

Or with rye:

rye add clifire

Quick Start

Create a simple CLI command using decorators. For example, save the following as fire/hello.py:

from clifire import command, out

@command.fire
def hello(cmd, user: str = "", _sudo: bool = False):
    """
    Display a greeting on the console.

    Args:
        user: Name of the user to greet. If empty, the current system user is used.
        _sudo: Run the command with sudo privileges.
    """
    if not user:
        sudo = 'sudo' if _sudo else ''
        user = cmd.app.shell(f"{sudo} whoami").stdout
    out.info(f'Hi {user}!')

Then run:

fire hello Rob

In action:

For more details, see our Quick Start Guide.

Documentation

The full documentation is available on GitHub Pages in English and Spanish. It covers topics such as:

• CliFire Basics
• Decorators
• Class-based Commands
• Options and Arguments
• Grouped Commands
• Output and Styling
• Configuration
• Templates
• Changelog
• Contributing

Development

CliFire is an open-source project, and contributions are welcome! If you find a bug, have a feature request, or want to contribute improvements, please open an issue or submit a pull request.

For development, we use Rye, a Python environment and dependency manager. Rye makes it easy to install dependencies and manage virtual environments. If you don't have it installed, you can follow the instructions on their website.

curl -sSf https://rye.astral.sh/get | bash

To contribute to CliFire:

1. Fork the repository on GitHub.

2. Clone your fork locally:

   git clone https://github.com/<your-username>/clifire.git
   cd clifire

3. Create a new branch for your feature or bug fix:

   git checkout -b feature/my-feature

4. Install development dependencies: If you are using Rye, you can install the development dependencies with:

   rye install --with dev

5. Run tests to ensure everything works:

   rye run pytest
   # or to check coverage:
   rye run coverage run -m pytest && rye run coverage html

   You can also use the fire coverage command to run the tests and generate the coverage report:

   rye run fire coverage

6. Update the CHANGELOG.md with your changes.

7. Commit and push your changes, and then create a pull request.

For further contribution details, please see our Contributing Guide.

License

CliFire is released under the MIT License. See the LICENSE file for details.