Support for relative datetimes

[AngellusMortis]

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the Typer documentation, with the integrated search.
• I already searched in Google "How to X in Typer" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to Typer but to Click.

Commit to Help

• I commit to help with one of those options 👆

Example Code

import typer
import dateparser

app = typer.Typer()

def relative_datetime(ctx: typer.Context, value: str, param: Parameter) -> datetime:
    if dt := dateparser.parse(value):
        return dt

    raise typer.BadParameter("Must be a ISO 8601 format or human readable relative format", ctx, param)

@app.callback()
def main(ctx: typer.Context, start: str) -> None:
   start_dt = relative_datetime(ctx, start, ctx.command.params[0])

# app "1 hour ago"
if __name__ == "__main__":
    typer.run(main)

Description

Support human readable/relative datetimes

Wanted Solution

The popular package dateparser already allows for parsing human readable/relative datetimes, such as "1 hour ago". It would be great if the CLI can automatically support this without a callback if the module is installed.

Wanted Code

import typer

app = typer.Typer()

@app.callback()
def main(ctx: typer.Context, start: datetime) -> None:
    pass

# app "1 hour ago"
if __name__ == "__main__":
    typer.run(main)

Alternatives

No response

Operating System

Linux

Operating System Details

No response

Typer Version

0.6.1

Python Version

3.10

Additional Context

No response

[YuriiMotov]

You can support custom types by specifying parser parameter:

from datetime import datetime
from typing import Annotated

import dateparser
import typer

app = typer.Typer()


def relative_datetime(value: str) -> datetime:
    if dt := dateparser.parse(value):
        return dt
    raise typer.BadParameter(
        "Must be a ISO 8601 format or human readable relative format"
    )


@app.callback()
def main(
    start: Annotated[datetime, typer.Argument(parser=relative_datetime)],
) -> None:
    typer.echo(start)


# app "1 hour ago"
if __name__ == "__main__":
    typer.run(main)

$ python main.py "1 hour ago"
2025-09-18 22:18:46.338319