Undocumented behavior (or bug) for default option name with metavar

[JonKing93]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

from typing import Annotated
import typer

def main(
    example: Annotated[str, typer.Option(metavar="EXAMPLE")] = None,
):
    pass

if __name__ == "__main__":
    typer.run(main)

Description

When I write a typer option, I expect the default option name to match the casing of the function parameters. For example, if I have a function parameter named example, then I expect the default invocation to be --example. Similarly, for a function parameter named MixedCASE, I'd expect the default invocation to be --MixedCASE.

However, in some circumstances, the casing of the option name seems to be inherited from metavar, rather than the function parameter. As best I can tell, this requires all of the following:

1. The typer.Option does not specify an alternate name
2. The typer.Option specifies a metavar string, and
3. The metavar string and function parameter name are a case-insensitive match.

For the code snippet above, I'd expect to invoke the "example" option using --example. But if you actually try this, e.g.

python example.py --example foo

you get an error No such option: --example because the function is expecting --EXAMPLE instead - it inherited the uppercase style from the metavar string.

I didn't see any mention of this in the option naming docs, so if this is intended behavior, then it would be helpful to mention it there.

Operating System

Linux, Windows

Operating System Details

No response

Project Version

0.27.3

Python Version

3.14.4

Additional Context

Uses rich v15.0.0

[kgeminicdev]

This is intentional since 0.27.0. It came in with PR #1863 ("Update metavar printing"), which stopped Typer from lowercasing or uppercasing parameter names. When no option name is given, the flag is built by get_default_option_flag_name in typer/main.py:

def get_default_option_flag_name(name: str, metavar: str | None) -> str:
    flag_name = name.replace("_", "-")
    if metavar is not None:
        meta_flag = metavar.replace("_", "-")
        if meta_flag.lower() == flag_name.lower():
            return meta_flag
    return flag_name

So when the metavar matches the parameter name case-insensitively, the metavar's spelling wins. tests/test_core.py::test_parameter_name_casing tests this directly: arg9: int = typer.Option(metavar="ARG9") is expected to accept --ARG9 and reject --arg9. It's also why MixedCASE now gives --MixedCASE. Before 0.27.0 the name was always lowercased.

You're right that the option naming docs don't mention it. To keep --example and still show EXAMPLE in help, declare the name explicitly:

def main(
    example: Annotated[str, typer.Option("--example", metavar="EXAMPLE")] = None,
):
    ...

Or use a metavar that isn't a case-insensitive match for the parameter name. A docs PR adding a note to the option name page would probably be welcome.

[JonKing93]

Got it, thanks! Sure, I'll see if I can find some time to put a docs PR in