clonf 0.4.1

Declaratively connect cli and config definition using pydantic

clonf

Declaratively connect cli and config definition using pydantic.

Why another?

There are a lot of tools out there which try to bring cli libraries and pydantic together, but they all seem to forget that more sophisticated applications need to be controlled via configuration files as well. clonf tries to solve this problem by focusing on compatibility with pydantic-settings and its configuration sources. This allows having a single source of truth for cli and configuration definition. clonf uses composition rather than inheritance and utilizes logic from pydantic and pydantic-settings to achieve this with as much simplicity and flexibility as possible. First versions focus on integration with click, but other cli libraries might receive interfaces as well in the future.

Key differences to other pydantic x cli libraries

• CLI behavior is opt-in.
• Designed to work well with pydantic-settings.
• As much as possible is done via annotations. Combined with pydantic best practices, this encourages creating a single source of truth inside your codebase.

Installation

clonf can be installed via pip or your favorite python package manager with different extras:

pip install clonf[all,click,settings]

Creating a CLI

click

Quickstart

from pydantic import BaseModel
from clonf import clonf_click, CliArgument, CliOption
from typing import Annotated
import click


class Arguments(BaseModel):
    name: Annotated[str, CliArgument()]


class Options(BaseModel):
    greeting: Annotated[str, CliOption()] = "Hello"


@click.command
@clonf_click
def cli(arguments: Arguments, options: Options) -> None:
    click.echo(f"{options.greeting} {arguments.name}")


if __name__ == "__main__":
    cli()

Using click types

Similar to pydanclick, the following types will be converted automatically:

Python type	Click type	CLI input format example
bool	click.BOOL	true, false
str	click.STRING	value
int	click.INT	1
float	click.FLOAT	1.2
Annotated[int, Field(lt=..., ge=...)	click.IntRange()	2
Annotated[float, Field(lt=..., ge=...)	click.FloatRange()	4.2
pathlib.Path	click.Path()	/etc/path
uuid.UUID	click.UUID	9b5a1c83-3b6a-46b1-9c79-4b67e02b0e0f
datetime.datetime, datetime.date	click.DateTime()	2025-10-19, 2025-10-19T19:10:42, 2025-10-19 19:10:42
Literal	click.Choice	value
dict	clonf.integrations.click.params.ClickMapping	key1=value1, key1=value1,key2=value2
list	clonf.integrations.click.params.ClickList	42, 42,187

Additionally, custom click types can be passed via annotations to have finer control over the resulting click type:

from pydantic import BaseModel
from typing import Annotated
from clonf import CliArgument
import pathlib
import click

class Config(BaseModel):
    file_path: Annotated[pathlib.Path, CliArgument(), click.Path(exists=True)]

Contributing

This project uses PDM as a package manager and pre-commit for linting before commits.

Read more about the tools and how to use them:

• PDM
• pre-commit