pydantic-cli

10.0.0 verified Sat May 09 auth: no python

Turn Pydantic defined data models into CLI tools with automatic argument parsing, help generation, and validation. Current version 10.0.0, requires Python >=3.10. Releases follow pydantic major versions with breaking changes.

pip install pydantic-cli

Common errors

error ModuleNotFoundError: No module named 'pydantic_cli' ↓

cause Library not installed or installed with different capitalization.

fix

Run 'pip install pydantic-cli' (hyphen, not underscore).

error AttributeError: module 'pydantic_cli' has no attribute 'run_and_exit' ↓

cause Using pydantic-cli v9 or earlier where the function was named differently or in a submodule.

fix

Upgrade to v10: 'pip install -U pydantic-cli'. For v9, use 'from pydantic_cli.app import CLI'.

error pydantic.errors.PydanticUserError: A custom validator must be a classmethod ↓

cause Using pydantic v2 validators incorrectly; pydantic-cli v10 expects pydantic v2 model validation.

fix

Ensure validators use @field_validator decorator from pydantic v2.

Warnings

breaking pydantic-cli v10 drops support for pydantic v1. Your models must use pydantic v2 syntax. ↓

fix If using pydantic v1, pin pydantic-cli<10.

gotcha Subcommands are not natively supported. Each script should handle a single command. ↓

fix Use a separate entry point per command or consider another library like typer or click.

deprecated The old pattern 'from pydantic_cli import CLI' is deprecated. Use run_and_exit instead. ↓

fix Replace 'CLI().run()' with 'run_and_exit()'.

Imports

run_and_exit

wrong

from pydantic_cli.app import run_and_exit

correct

from pydantic_cli import run_and_exit

run_and_exit was moved to top-level package in v10

AppConfig

wrong

from pydantic_cli.config import AppConfig

correct

from pydantic_cli import AppConfig

AppConfig is now exported from pydantic_cli

Quickstart

Basic example: define a Pydantic model as CLI arguments and a runner function.

import sys
from pydantic import BaseModel
from pydantic_cli import run_and_exit

class Options(BaseModel):
    name: str
    count: int = 1

def runner(opts: Options) -> None:
    for _ in range(opts.count):
        print(f'Hello {opts.name}')

if __name__ == '__main__':
    run_and_exit(Options, runner, description='A simple greeting app')