Clarification needed for boolean option behavior (--flag / --no-flag)

[Songcheng-Xie]

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 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 tutorials 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

app = typer.Typer()

@app.command()
def hello(name: str):
    """Greet a person by name."""
    typer.echo(f"Hello, {name}!")

@app.command()
def goodbye(name: str, formal: bool = False):
    """Bid farewell to a person by name."""
    if formal:
        typer.echo(f"Goodbye, Mr./Ms. {name}.")
    else:
        typer.echo(f"Goodbye, {name}!")

if __name__ == "__main__":
    app()

Description

When I was running the README example that uses a boolean parameter:

def goodbye(name: str, formal: bool = False):

I was confused why the command-line syntax uses:

--formal / --no-formal

instead of passing boolean values like:

--formal True
--formal False

As a beginner, I expected boolean parameters to accept values directly.

It would help newcomers if the documentation explained:

1. Why Typer (and Click) treat boolean parameters as flags rather than value arguments.
2. Why flags do not accept True/False values in CLI design.
3. The meaning of --formal = True and --no-formal = False.
4. That this follows general Unix CLI conventions (e.g., --force, --verbose).

This is a common confusion point for new users, and adding a small explanation in the tutorial or README would greatly improve clarity.

I would be happy to submit a PR to improve this part of the documentation.

Operating System

macOS

Operating System Details

macOS Ventura Version 13.3.1

Typer Version

0.20.0

Python Version

3.12

Additional Context

No response