Currently, using add_subparsers() means that the entire list of subcommands is added to the main usage message. This gets rather unwieldy when there are a lot of subcommands.

It would be nice if the add_subparsers() method accepted a "metavar" argument that would be substituted into the usage string instead of using the subparser list directly.

Have you tried setting the metavar property on the return value of add_subparsers()?  I tried this, and it seems to work.

It looks like the logic for _metavar_formatter() is the same no matter what the action type (specifically _SubParsersAction in this case):

http://hg.python.org/cpython/file/e81cad0c722a/Lib/argparse.py#l554

Actually, it looks like add_subparsers() may already support passing a metavar argument, but it's just not documented?

Thanks to Issue 11807, the documentation now lists “metavar”. (However, it looks like a positional argument, rather than keyword-only, and its use seems to be discouraged, but those issues are not specific to “metavar”.)

Some points specific to “metavar” that I think could be clarified:

1. Metavar seems to affect the placeholder in the “usage” message, and a heading that precedes a multi-line list of commands, but it does not affect the presentation of the multi-line list itself.

2. The relationship between the “metavar” parameter of “add_argument” and “add_subparsers” needs clarifying. At the moment, there is a hyperlink, which implies that the description of add_argument’s parameter applies to add_subparsers. But it only discusses the “dest” parameter and CLI options (a.k.a. “optionals”), neither of which make sense in the context of subcommands. Issue 29030 (choices vs metavar) may be related.