0.27 Option flag getting clobbered

[riklopfer]

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

# /// script
# requires-python = ">=3.14"
# dependencies = ["typer==0.27"]
# ///


from typing import Annotated

import typer


def main(    fuzzy_muffins: Annotated[
    str,
    typer.Option(
        help="Fuzzy muffins",
        show_default=True,
        metavar="FUZZY_MUFFINS",
    ),
] = "Very fuzzy") -> None:
    print(f"Hello {fuzzy_muffins}")


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

Description

• run uv run arg_fuzzy.py --help

Usage: arg_fuzzy.py [OPTIONS]

╭─ Options ──────────────────────────────────────────────────────╮
│ --FUZZY-MUFFINS        FUZZY_MUFFINS  Fuzzy muffins            │
│                                       [default: Very fuzzy]    │
│ --help                                Show this message and    │
│                                       exit.                    │
╰────────────────────────────────────────────────────────────────╯

expected

 Usage: arg_fuzzy.py [OPTIONS]

╭─ Options ──────────────────────────────────────────────────────╮
│ --fuzzy-muffins        FUZZY_MUFFINS  Fuzzy muffins            │
│                                       [default: Very fuzzy]    │
│ --help                                Show this message and    │
│                                       exit.                    │
╰────────────────────────────────────────────────────────────────╯

note the capitalization on the flag --FUZZY-MUFFINS

Operating System

macOS

Operating System Details

No response

Project Version

0.27

Python Version

Python 3.14.5

Additional Context

No response

[apoorva-01]

It's deliberate, which took me a minute to believe. Name the flag explicitly and you get both halves of what you want:

fuzzy_muffins: Annotated[
    str,
    typer.Option("--fuzzy-muffins", help="Fuzzy muffins", metavar="FUZZY_MUFFINS"),
] = "Very fuzzy"

0.27 stopped force-lowercasing generated flag names (#1863, it's in the breaking changes list). The rule that bites you lives in get_default_option_flag_name: if your metavar matches the param name case-insensitively once underscores become dashes, the metavar's casing wins the flag. There's a test pinning exactly this, test_parameter_name_casing in tests/test_core.py, where arg9: int = typer.Option(metavar="ARG9") gets invoked as --ARG9. Passing an explicit param decl skips that path, so metavar goes back to only describing the value.

One thing to watch: this is a parse change, not just help cosmetics. On 0.27 --fuzzy-muffins dies with No such option, so anything with an ALL_CAPS metavar on an Option is a breaking CLI change for its users. Given #1863's stated goal was avoiding ALL CAPS, an option flag coming out shouting feels like an unintended edge of the rule. I'd open an issue.

[riklopfer]

Thanks! I'm okay with adding --fuzzy-muffins to the Option spec