Commands are the core component of a CLI, running a user-defined function that may be parameterized with arguments or options.

Commands may be included within Groups, which usually contain a set of related commands.

Commands may be executed using run().

See also

The Click API documentation does a great job at clarifying the following command-line terminology:

Understanding function signatures#

To understand how Feud converts a function into a click.Command, consider the following function.


import feud

def func(arg1: int, arg2: str, *, opt1: float, opt2: int = 0):

if __name__ == "__main__":

This function signature consists of:

  • two positional parameters arg1 and arg2,

  • two keyword-only parameters opt1 and opt2.


The * operator in Python is used to indicate where positional parameters end and keyword-only parameters begin.

When calling func in Python:

  • values for the positional parameters can be provided without specifying the parameter name,

  • values for the keyword-only parameters must be provided by specifying the parameter name.

func(1, "hello", opt1=2.0, opt2=3)

where arg1 takes the value 1, and arg2 takes the value "hello".

Similarly, when building a click.Command, Feud treats:

  • positional parameters as arguments (specified without providing a parameter name),

  • keyword-only parameters as options (specified by providing a parameter name).

$ python 1 hello --opt1 2.0 --opt2 3

Note that --opt1 is a required option as it has no default specified, whereas --opt2 is not required.

API reference#

feud.core.command(func=None, /, *, negate_flags=None, show_help_defaults=None, show_help_datetime_formats=None, show_help_envvars=None, pydantic_kwargs=None, rich_click_kwargs=None, config=None, **click_kwargs)#

Decorate a function and convert it into a click.Command with automatically defined arguments, options and help documentation.

  • func (Callable | None) – Function used to generate a command.

  • negate_flags (bool | None) – Whether to automatically add a negated variant for boolean flags.

  • show_help_defaults (bool | None) – Whether to display default parameter values in command help.

  • show_help_datetime_formats (bool | None) – Whether to display datetime parameter formats in command help.

  • show_help_envvars (bool | None) – Whether to display environment variable names in command help.

  • pydantic_kwargs (dict[str, Any] | None) – Validation settings for pydantic.validate_call_decorator.validate_call().

  • rich_click_kwargs (dict[str, Any] | None) –

    Styling settings for rich-click.

    See all available options here (as of rich-click v1.7.2).

  • config (Config | None) –

    Configuration for the command.

    This argument may be used either in place or in conjunction with the other arguments in this function. If a value is provided as both an argument to this function, as well as in the provided config, the function argument value will take precedence.

  • **click_kwargs (Any) – Keyword arguments to forward click.command().


The generated command.

Return type:



>>> import feud
>>> @feud.command(name="my-command", negate_flags=False)
... def f(arg: int, *, opt: int) -> tuple[int, int]:
...     return arg, opt
>>>, ["3", "--opt", "-1"], standalone_mode=False)
(3, -1)

See also


Run a command or group.


Configuration defaults.