Cleo

Warnings

• breaking Cleo versions 1.0.0 and 2.0.0 removed the `clikit` dependency, signifying a major internal refactoring. Code relying on `clikit` directly or specific `clikit`-based behaviors within Cleo will break.
  Fix: Review your code for direct or indirect `clikit` usage. Adapt to Cleo's native implementations for input/output handling, command definition, and other CLI functionalities. The library is now self-contained in this regard.
• breaking The `Terminal` class was removed and replaced with `shutil.get_terminal_size()` from Python's standard library. Direct calls to `cleo.terminal.Terminal` will fail.
  Fix: Replace usages of `cleo.terminal.Terminal` with `shutil.get_terminal_size()` for terminal dimension retrieval.
• breaking The exception hierarchy changed in versions 1.0.0 / 2.0.0. Specifically, `CleoException` was renamed or replaced by `CleoError`.
  Fix: Update exception handling blocks to catch `CleoError` instead of `CleoException` and adjust for any other related exception class changes.
• breaking Doc comment-based command configuration (where arguments and options were defined in the command's docstring) was removed in versions 1.0.0 / 2.0.0.
  Fix: Migrate command argument and option definitions to use the `arguments` and `options` class variables with `cleo.helpers.argument` and `cleo.helpers.option` decorators. Refer to the quickstart example for the new syntax.
• gotcha Cleo version 1.0.0 was yanked shortly after its release due to compatibility issues with other projects (e.g., Poetry) that depended on its pre-release versions. Version 2.0.0 was released immediately after with no source code changes to effectively replace 1.0.0.
  Fix: Avoid using `cleo==1.0.0`. If targeting the feature set introduced in `1.0.0`, ensure you use `cleo>=2.0.0` (e.g., `pip install 'cleo>=2.0.0,<3.0.0'`).

Install

• pip install cleo Install latest version

Imports

• Application

  from cleo.application import Application

  While 'from cleo import Application' might work in some contexts, the explicit path 'from cleo.application import Application' is recommended for clarity and directness, as shown in official examples.
• Command

  from cleo.commands.command import Command

  Similar to Application, importing Command from its explicit module path 'cleo.commands.command' is the precise and recommended approach, as seen in the library's internal structure and modern examples.
• argument

  from cleo.helpers import argument

  Since Cleo v2.0.0 (and effectively v1.0.0), the recommended way to define command arguments is using the `argument` helper from `cleo.helpers`, replacing the older `InputArgument` class and docstring-based definitions.
• option

  from cleo.helpers import option

  Corresponding to `argument`, the `option` helper from `cleo.helpers` is now the standard for defining command options, replacing `InputOption` and docstring-based methods in versions v2.0.0+.
• CleoError

  from cleo.exceptions import CleoError

  The exception hierarchy was refactored in Cleo v1.0.0 (effectively v2.0.0), with `CleoException` being replaced by `CleoError`.

Quickstart

This quickstart demonstrates how to create a basic command-line application with Cleo. It defines a `GreetCommand` that accepts an optional name argument and a 'yell' flag. The command uses `cleo.helpers.argument` and `cleo.helpers.option` for modern argument and option definitions. An `Application` instance registers the command, and a simulated `io` stream is used to run the command programmatically for demonstration purposes, mimicking command-line execution.

import os
from cleo.application import Application
from cleo.commands.command import Command
from cleo.helpers import argument, option


class GreetCommand(Command):
    name = "greet"
    description = "Greets someone"

    arguments = [
        argument("name", description="Who do you want to greet?", optional=True)
    ]
    options = [
        option("yell", "y", description="If set, the task will yell in uppercase letters", flag=True)
    ]

    def handle(self):
        name = self.argument("name")
        if name:
            text = f"Hello {name}"
        else:
            text = "Hello"

        if self.option("yell"):
            text = text.upper()

        self.line(text)


application = Application("My CLI App", "1.0.0")
application.add(GreetCommand())

if __name__ == "__main__":
    # Example of how to run, in a real app this would be called via command line
    # e.g., `python your_script.py greet John --yell`
    # For quickstart, we'll simulate it for programmatic execution and testing
    try:
        # Simulate a command-line call for demonstration
        # In a real scenario, this would be invoked via sys.argv
        from cleo.io.buffered_io import BufferedIO
        from cleo.io.inputs.string_input import StringInput
        from cleo.io.outputs.buffered_output import BufferedOutput
        
        # Example: running 'greet John --yell'
        input_stream = StringInput('greet John --yell')
        output_stream = BufferedOutput()
        error_stream = BufferedOutput()
        
        io = BufferedIO(input_stream, output_stream, error_stream)
        application.run(io)
        
        print("\n--- Output ---")
        print(output_stream.fetch())
        print("--- Error ---")
        print(error_stream.fetch())
        print("--------------")

        # Example: running 'greet'
        input_stream_no_args = StringInput('greet')
        output_stream_no_args = BufferedOutput()
        error_stream_no_args = BufferedOutput()

        io_no_args = BufferedIO(input_stream_no_args, output_stream_no_args, error_stream_no_args)
        application.run(io_no_args)

        print("\n--- Output (No Args) ---")
        print(output_stream_no_args.fetch())
        print("--- Error (No Args) ---")
        print(error_stream_no_args.fetch())
        print("------------------------")

    except Exception as e:
        print(f"An error occurred: {e}")