cliff Command Line Interface Formulation Framework

4.13.3 · active · verified Sat Apr 11

cliff (Command Line Interface Formulation Framework) is a Python library for building structured command-line applications, commonly used for OpenStack clients and other complex CLIs. It provides base classes for application structure, command registration, argument parsing, and consistent output formatting. The current version is 4.13.3, and it maintains a regular release cadence with active development.

Warnings

breaking Python 3.10+ is now required. Additionally, build system dependencies shifted from 'pbr' to 'setuptools-scm' or direct 'setuptools' for project setup.
Fix: Ensure your project runs on Python 3.10 or newer. Update your `pyproject.toml` or `setup.cfg` to use `setuptools-scm` or `setuptools` for package metadata and entry points, removing any 'pbr' specific configurations.
breaking The `log_file` option for `App.run()` and related logging configuration methods have been removed.
Fix: Configure logging using Python's standard `logging` module before `App.run()` is called. `cliff` provides `App.configure_logging()` for basic setup or you can implement a custom configuration.
gotcha Commands are discovered via Setuptools entry points (e.g., `[cliff.commands]` or custom groups like `[mycli_entrypoints]` in `setup.cfg` or `pyproject.toml`). Misconfiguring or omitting these entry points will prevent your commands from being found by the CLI application.
Fix: Verify your `pyproject.toml` (or `setup.cfg`) correctly defines entry points under the `[project.entry-points."<your_entry_point_group>"]` section, mapping command names to their respective `Command` class paths.
gotcha `Lister` and `ShowOne` command types expect specific return value structures. `Lister` expects `(column_names, data_rows)` and `ShowOne` expects `(column_names, data_item)` where `data_rows` is a list of tuples/lists and `data_item` is a single tuple/list.
Fix: Ensure `take_action` methods for `Lister` and `ShowOne` commands return a tuple `(column_names, data)` conforming to these types. Incorrect structures will lead to output errors or unexpected behavior.

Install

pip install cliff Install cliff

Imports

App
```
from cliff.app import App
```
Base class for the CLI application itself.
Command
```
from cliff.command import Command
```
Base class for individual CLI commands. Often confused with the top-level 'cliff' module.
Lister
```
from cliff.lister import Lister
```
A Command subclass for commands that list items, expecting (column_names, data) as return.
ShowOne
```
from cliff.showone import ShowOne
```
A Command subclass for commands that show details of a single item, expecting (column_names, data) as return.

Quickstart

This quickstart demonstrates a minimal `cliff` application with one command. To make this a discoverable CLI tool, you would typically define entry points in your `pyproject.toml` (or `setup.cfg`). For example, under `[project.entry-points."mycli_entrypoints"]`, you would add `mycommand = my_module:MyCommand` for command discovery, and under `[project.scripts]`, you would add `mycli = my_module:main` to create the executable. The example manually registers the command for simplicity, allowing it to be run directly.

import sys
from cliff.app import App
from cliff.command import Command
from cliff.commandmanager import CommandManager

class MyCommand(Command):
    """A simple example command."""

    def get_parser(self, prog_name):
        parser = super().get_parser(prog_name)
        parser.add_argument(
            '--name',
            dest='name',
            default='World',
            help='Name to greet'
        )
        return parser

    def take_action(self, parsed_args):
        print(f"Hello, {parsed_args.name}!")

class MyCLIApp(App):

    def __init__(self):
        super().__init__(
            description='My simple cliff-based CLI',
            version='1.0',
            command_manager=CommandManager('mycli_entrypoints'),
            deferred_help=True,
        )

    def initialize_app(self, argv):
        self.LOG.debug('initialize_app')

    def prepare_to_run(self, argv):
        self.LOG.debug('prepare_to_run')

    def clean_up(self, cmd, result, err):
        self.LOG.debug('clean_up')
        if err:
            self.LOG.debug(f'An error occurred: {err}')


def main(argv=sys.argv[1:]):
    # For a real app, commands are typically registered via setup.cfg or pyproject.toml entry points.
    # Example: In pyproject.toml, under [project.entry-points."mycli_entrypoints"]
    #          'mycommand = my_module:MyCommand'
    #          And under [project.scripts]
    #          'mycli = my_module:main'
    # For this quickstart, we manually register the command:
    app = MyCLIApp()
    app.command_manager.add_command('mycommand', MyCommand)

    return app.run(argv)

if __name__ == '__main__':
    # Simulate running 'mycli mycommand --name Registry' from the command line
    sys.exit(main(['mycommand', '--name', 'Registry']))

view raw JSON →