📝 Clarify single-command vs multi-command behaviour in README

[MorgenPronk]

This PR adds a note in the README explaining that Typer treats single-command CLIs differently than multi-command CLIs.

This behavior can be surprising for new users (like myself), because calling the command by name (e.g., python cli.py hello Camila) results in an error when only one command is defined — Typer silently expects python cli.py Camila instead.

While this is explained in the full documentation, the README contains a similar example and is often the first place beginners look. A brief clarification here could help save users some confusion — especially those coming from FastAPI, where the number of wrapped functions doesn’t affect how the app is invoked.

Related issues:

#315 - this PR directly addresses confusion raised here.

#445 - is tangentially related in that it also highlights behavioral differences when only one subcommand exists.

I’ve also explored making this behavior configurable (i.e., supporting both styles of invocation), and I’d be happy to help further if there’s interest. But this change is a simple, non-breaking way to surface the existing behavior earlier for new users.

Let me know if you'd prefer the note be placed elsewhere, want to reword it, or would like help drafting a fuller fix later on.

[svlandeg]

Thanks!

I think I would personally move this note to after the part where python main.py hello Camila and python main.py goodbye Camila are executed - i.e. right before the section "recap". I would also try to make the note as short as possible, while referring to the more detailed section.

[MorgenPronk]

updated the PR based on @svlandeg’s feedback:

• Moved the note to right before the Recap section.
• Simplified the wording as suggested.
• Adjusted the formatting so it matches the style of other notes in the README.
  I also regenerated README.md from docs/index.md again.

Let me know if you’d like me to tweak the formatting further!

[svlandeg]

This looks good to me. While I know we want to be mindful of keeping this page nice and short, I definitely can see how the difference between single and multi command usage is confusing, and a (relatively quick) note to address that seems like a good idea to me.

As always I'll defer to Tiangolo for the final decision though.

[github-actions]

📝 Docs preview for commit ef31145 at: https://40a5e995.typertiangolo.pages.dev

Modified Pages

• https://40a5e995.typertiangolo.pages.dev/ - (before)

[tiangolo]

Sounds good, thanks @MorgenPronk! ☕

And thanks for the help @svlandeg and @YuriiMotov 🍰